@topy-ai/maggie 0.8.15 → 0.8.17

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.15`,補齊除 Q 外所有設計類的覆蓋(深入研究先前略讀的桌面編輯器/動畫工具,只借思路不抄碼):maggie_image.py 新增 svg-export(Inkscape)/composite/look,新增 design-editor-patterns reference,並擴充 web-animation/generative-visuals/video-timeline;docs/design-coverage-audit.md 逐 repo 確認。先前 0.8.14 新增 `maggie-ai-media`(去背/放大/arm's-length ComfyUI 的命令生成器,自身不下載模型、不用 GPU),讓 Q 類達到同級;重型執行仍受成本把關。先前 0.8.13 新增 AI 媒體生成規劃 reference(Q 類:自託管模型概覽、程式碼授權≠權重授權規則、商用安全子集 rembg/Real-ESRGAN、成本/BYOK 守則;實際建置待明確許可)。先前 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
+目前 npm 版本為 `0.8.17`,收尾最後兩個完整源碼覆蓋缺口:`inkscape/inkscape`(GitHub 鏡像僅 2 檔 stub,改從 GitLab clone 7053 檔逐一代碼級研究)與 L 類 web 動效庫(先前僅 README/API 層,現讀完整源碼)。net-new(借鑑邏輯非程式碼):`maggie_image.py` 新增 `svg-export --actions`(一次 Inkscape 呼叫完成清理+展平+匯出)與 `svg-query`(元素 id + 邊界框);`web-animation-patterns` 補上源碼級更正(AOS 其實是 scroll+throttle 而非 IntersectionObserver;lenis `autoRaf` 預設 false 且有 `respectReducedMotion`;typed.js 為 GPL-3.0 且無減動支援)與新點子(設計師友善的彈簧詞彙、mojs `Burst` 微互動條目、anime v4 網格 stagger、pixijs 超出範圍邊界註記)。`0.8.16` 把先前僅 README 的 repo 解稀疏為完整源碼並逐一代碼級研究(驗證所有 reference 並補 net-new:Remotion delayRender gate、opentoonz BSD 可移植的 xsheet 時間線、綠幕/LUT/卡拉OK 濾鏡、whisper turbo + 字幕旗標、Babylon NullEngine 無頭),並新增 maggie_image.py trim/auto-orient 與更豐富的 captions 旗標。先前 0.8.15 補齊除 Q 外所有設計類的覆蓋:maggie_image.py 新增 svg-export(Inkscape)/composite/look,新增 design-editor-patterns reference,並擴充 web-animation/generative-visuals/video-timeline;docs/design-coverage-audit.md 逐 repo 確認。先前 0.8.14 新增 `maggie-ai-media`(去背/放大/arm's-length ComfyUI 的命令生成器,自身不下載模型、不用 GPU),讓 Q 類達到同級;重型執行仍受成本把關。先前 0.8.13 新增 AI 媒體生成規劃 reference(Q 類:自託管模型概覽、程式碼授權≠權重授權規則、商用安全子集 rembg/Real-ESRGAN、成本/BYOK 守則;實際建置待明確許可)。先前 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

@@ -89,7 +89,7 @@ Maggie keeps the existing project foundation and asks for decisions before
 shared routes, analytics, or publishing boundaries change. The current
 package ships 39 installable skills and a local-first MaggieDash foundation.
 
-This package is `0.8.15` — closes the non-Q design coverage gap (deep codebase study of the desktop editors/animation tools): `maggie_image.py` gains svg-export/composite/look, a new design-editor-patterns reference, and growth in web-animation/generative-visuals/video-timeline references. `0.8.14` adds `maggie-ai-media` (bg removal / upscaling / arm's-length ComfyUI as a command generator; no model downloads or GPU itself). `0.8.13` adds the AI-media-generation planning reference (category Q: licensing + safe subset + cost guardrails; build gated on go-ahead). `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.
+This package is `0.8.17` — closes the last two full-source coverage gaps: `inkscape/inkscape` (GitHub is a 2-file stub; studied from GitLab, 7053 files) and the L web-animation libraries (now read at source). `maggie_image.py` gains `svg-export --actions` (clean+flatten+export in one Inkscape call) + `svg-query` (element ids + bounding boxes); `web-animation-patterns` gets source corrections (AOS is scroll+throttle not IntersectionObserver; lenis `autoRaf` default false; typed.js GPL-3.0) and new ideas (designer-spring vocabulary, mojs `Burst` entry, anime v4 grid-stagger, pixijs out-of-scope note). `0.8.16` — de-sparses the earlier README-only repos to full source and studies them at code level (confirm + net-new: Remotion delayRender gate, opentoonz BSD port target, green-screen/LUT/karaoke filters, whisper turbo + caption flags, Babylon NullEngine), plus maggie_image.py trim/auto-orient and richer captions flags. `0.8.15` closed the non-Q design coverage gap: `maggie_image.py` gains svg-export/composite/look, a new design-editor-patterns reference, and growth in web-animation/generative-visuals/video-timeline references. `0.8.14` adds `maggie-ai-media` (bg removal / upscaling / arm's-length ComfyUI as a command generator; no model downloads or GPU itself). `0.8.13` adds the AI-media-generation planning reference (category Q: licensing + safe subset + cost guardrails; build gated on go-ahead). `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

@@ -9,7 +9,7 @@ Distilled from the reference library's R-category projects.
 
 | 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`) |
+| openai-whisper | `whisper IN --model turbo --output_format srt --output_dir DIR` (default model is now **`turbo`** = large-v3-turbo; formats `txt/vtt/srt/tsv/json`) | 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 |
 
@@ -38,4 +38,24 @@ Model size trades speed for accuracy: `tiny` / `base` (fast, rough) -> `small` /
   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).
 
+## Caption-shaping flags (built into openai-whisper)
+
+The core CLI already does what we previously routed to whisperX or post-processing
+(`maggie_video.py captions` exposes these):
+
+- `--word_timestamps True` - word-level timings (whisperX still wins on alignment +
+  diarization, but core whisper now has them).
+- `--highlight_words True` - **karaoke-style** per-word highlight in SRT/VTT (the
+  social-caption effect); render the ASS with ffmpeg `subtitles`.
+- `--max_line_width` / `--max_line_count` / `--max_words_per_line` - native line
+  wrapping so captions fit the channel safe-area, no post-processing.
+- `--initial_prompt "<brand, product names>"` - bias the model toward correct brand/
+  jargon spelling (the concrete mitigation for the mishears-brand-terms risk; still
+  human-review).
+- Anti-hallucination over music/silence: `--hallucination_silence_threshold`,
+  `--compression_ratio_threshold`, `--logprob_threshold`, `--no_speech_threshold` -
+  worth setting for music-bed marketing clips.
+- `--task translate` (foreign audio -> English subs), `--clip_timestamps` (only given
+  ranges).
+
 See `maggie-video` for the subcommands and the burn-in / soft-mux / compile options.

package/bundled-references/design-editor-patterns.md

@@ -15,8 +15,12 @@ the image is reconstructed by replaying the stack. Borrow this as a maggie "imag
 recipe": a small JSON `[ {op, params}, ... ]` stored next to the original and replayed
 by `maggie_image.py` (each op -> an ImageMagick/sharp command). It is **reproducible,
 auditable, re-editable, and batchable** - apply one "look" recipe to every photo in a
-campaign for consistent brand grading. `darktable-cli <in> <sidecar.xmp> <out>` renders
-from such a stack (GPL binary, arm's-length).
+campaign for consistent brand grading. `darktable-cli <input> [sidecar.xmp]
+<output-dir>` renders from such a stack (XMP optional/auto-discovered, final arg is a
+**directory**; GPL binary, arm's-length). Two source details worth adopting: **params
+versioning** (each module keeps `legacy_params` for forward-compatible migration -
+version your recipe ops) and **"Styles" = saved reusable history** (name a look once,
+apply to many).
 
 ## LLM-generatable scene / diagram formats
 
@@ -75,3 +79,26 @@ only: penpot (MPL), tldraw (custom), krita/krita-ai-diffusion (GPL), drawio icon
 MIT and freely borrowable as ideas (still reimplement, don't bulk-copy): excalidraw,
 Method-Draw, rough.js, Pinta. drawio code Apache-2.0; its diagram output is
 unrestricted.
+
+## From full-source study (net-new)
+
+- **tldraw** - the LLM mutation surface is `editor.createShapes/updateShapes/
+  deleteShapes` (batch partial mutations); the store ships schema **migration
+  sequences**, a composable **validation layer**, and a **side-effects manager**
+  (before/after create/change/delete hooks). `parentId` can be a page *or* a shape;
+  pages carry a fractional `index`. Adopt the batch-mutation + validate + migrate
+  shape as the model for an agent-written canvas doc.
+- **penpot** - **design tokens are W3C DTCG** (import/export + aliasing), components
+  have **variants**, shapes carry **flex/grid layout**; the agent boundary is an
+  **official MCP server talking to a sandboxed in-app plugin over WebSocket** - a
+  strong arm's-length model for making a design doc agent-writable (mirrors Maggie's
+  own MCP posture).
+- **drawio** - the `mxConstants` STYLE_* key table is a **validated allow-list** for
+  LLM-emitted styles; `mxEdgeStyle` routing + hierarchical/tree/organic **auto-layout**
+  mean a generated node+edge list can self-position; `.drawio` pages are often
+  **deflate+base64** compressed.
+- **krita** - an **adjustment/filter layer holds a serialized filter config** = a
+  non-destructive recipe living in the layer stack; ops are **mask/selection-scoped**;
+  `.kra` is `zip(manifest XML + per-layer blobs)`; a **Python scripting API** and a
+  JSON-manifest plugin boundary let a generative backend register like any filter -
+  the "AI as a swappable backend" posture.

package/bundled-references/ffmpeg-recipes.md

@@ -128,3 +128,24 @@ maggie tool maggie_video.py compile --spec timeline.json   # declarative timelin
 maggie tool maggie_video.py --run encode --input in.mov --output out.mp4   # actually runs
 maggie tool maggie_video.py presets
 ```
+
+## More filters worth reaching for (confirmed in libavfilter)
+
+- **Green-screen / keying** (UGC, product on a brand background):
+  `chromakey=0x00FF00:0.1:0.0` (or `colorkey`), clean fringes with `despill`.
+- **Fade to/from black** (distinct from clip crossfade): `fade=t=in:st=0:d=0.5`,
+  `fade=t=out:st=9.5:d=0.5`.
+- **Brand color grade / LUT**: `lut3d=brand.cube`, or `curves`/`eq`/`colorbalance`/`hue`.
+- **Karaoke captions**: `subtitles=in.ass` with a full ASS file (word highlight) -
+  pairs with whisper `--highlight_words` ([captions](captions-transcription.md)).
+- **Focus/credits**: `gblur` + `vignette`; `scroll` for scrolling outros.
+- **GPU fast path** when hardware is present: `overlay_cuda`/`overlay_vulkan`,
+  `xfade_opencl` for long renders.
+
+## Target-filesize social presets (HandBrake idea)
+
+Beyond aspect, encode to **fit under a platform's upload cap**: pick a two-pass video
+bitrate from the cap and duration - `bitrate_bits = size_bytes * 8 / duration - audio`
+- e.g. "25 MB / 30 s / 1080p". A named preset bundles `(upload cap, max duration) ->
+resolution + bitrate`. (HandBrake ships exactly these as "Social 25 MB 30 Seconds"
+presets.)

package/bundled-references/generative-visuals.md

@@ -119,3 +119,26 @@ nannou - licenses in the table above. Capture pipeline: see
   prompting, ControlNet/IP-Adapter conditioning), see
   [AI media generation](ai-media-generation.md) and
   [design editor patterns](design-editor-patterns.md).
+
+### Headless capture + 3D export (from full-source study)
+
+How to render these engines **without a screen**, and extra output formats worth
+knowing:
+
+- **Babylon.js `NullEngine`** (Apache-2.0) - first-class **server-side headless**
+  rendering (no GPU/canvas); the cleanest headless story for render-automation jobs,
+  plus a built-in **procedural-texture library** (brick/cloud/fire/marble/noise/wood),
+  `CreateScreenshotUsingRenderTarget` for 4K+ stills from a small viewport, and
+  **NodeMaterial** (shaders serialize to JSON - an LLM-emittable look). This is the
+  concrete reason to pick Babylon over three for automation.
+- **three.js** (MIT) - `readRenderTargetPixels()`/`...Async` read pixels from an
+  offscreen `WebGLRenderTarget` (true headless high-res, not on-screen canvas);
+  **SVGRenderer** emits a 3D scene as editable SVG; **USDZExporter** turns a 3D product
+  into a free **iOS AR Quick Look** asset; **GPUComputationRenderer** (ping-pong FBO
+  sim: flocking/fluid) = a living, seeded generative hero background.
+- **openFrameworks** (MIT) - `ofFbo` offscreen framebuffer for arbitrary-res stills;
+  **ofxEmscripten** compiles a desktop sketch to WebAssembly for the browser;
+  **ofxSvg** parses + emits structured SVG.
+- **Processing** - `PSurfaceNone` (headless) and `createGraphics(big)` (render larger
+  than the screen -> high-res still). License at feature granularity: core raster is
+  LGPL, but **SVG/PDF export is in non-core (GPL)** - reimplement, don't vendor.

package/bundled-references/image-recipes.md

@@ -103,6 +103,36 @@ inkscape in.svg --export-id=badge --export-id-only --export-type=png --export-fi
 inkscape in.svg --export-type=png --export-dpi=300 --export-area-page --export-filename=print.png
 ```
 
+**From the real source (GitLab `inkscape/inkscape`, 1.5-dev — the GitHub mirror is a
+stub; CLI flags above all confirmed current against `man/inkscape.pod.in`).** Three
+net-new capabilities worth adopting, all still arm's-length (no GPL vendored):
+
+- **Actions pipeline + batch (`--actions` / `--shell`).** One invocation can run an
+  ordered list of verbs, so a cleanup+flatten+export is a single call instead of a
+  chain. `maggie_image.py svg-export` can emit this for a "clean then export" job:
+  ```bash
+  inkscape in.svg \
+    --actions="select-all;object-to-path;vacuum-defs;export-plain-svg;export-filename:flat.svg;export-do"
+  # batch many files through one long-lived process (no per-file startup cost):
+  inkscape --shell < actions.txt      # one actions line per file, ending in export-do
+  ```
+  Useful actions: `object-to-path` / `all-objects-to-paths` (outline shapes+text),
+  `path-simplify`, boolean `path-union` / `path-difference` / `path-intersection`,
+  `vacuum-defs` (drop unused defs — shrinks file), and the `export-*` action family.
+  `inkscape --action-list` prints every verb.
+- **Geometry query (`--query-all` / `--query-id`).** Discover element ids and their
+  bounding boxes *before* `--export-id` slicing, so a generated slice list is correct:
+  ```bash
+  inkscape in.svg --query-all          # id,x,y,w,h per object (CSV) — feed --export-id
+  inkscape in.svg --query-id=badge --query-x --query-y --query-width --query-height
+  ```
+  `maggie_image.py svg-query` emits this (pairs with the per-id export above).
+- **Extra export flags:** `--export-page=all|N` + `--export-margin` (multi-page PDF/
+  SVG slicing), `--export-overwrite`, `--export-png-color-mode=Gray_8|RGBA_16` and
+  `--export-png-use-dithering`, `--export-pdf-version=1.5` / `--export-ps-level=3`,
+  `--export-latex` (PDF+LaTeX overlay for papers), `--export-plain-svg` (strip
+  Inkscape namespaces for clean handoff).
+
 ## Layered composite + named looks (Pinta vocabulary)
 
 Blend modes map from a raster editor's layer stack onto ImageMagick `-compose`:
@@ -121,3 +151,16 @@ non-destructive edit recipe): `grayscale` (`-colorspace Gray`), `sepia`
 `maggie_image.py composite` and `maggie_image.py look` generate these. For a
 reusable, batchable edit *recipe* (a JSON stack of named ops applied to many photos),
 see [design editor patterns](design-editor-patterns.md).
+
+## More ImageMagick ops worth baking in (confirmed in source)
+
+- **`-auto-orient`** first in every pipeline - fixes sideways phone photos by EXIF
+  (`maggie_image.py` resize/social/trim already prepend it).
+- **`-thumbnail WxH`** - metadata-stripping fast resize; a better default than
+  `-resize` for web/OG thumbnails.
+- **`-fuzz N% -trim +repage`** - trim a uniform border or cut a product/logo out of
+  its background (`maggie_image.py trim`).
+- **`-clut` / `-hald-clut`** - repeatable LUT brand grading (raster equivalent of
+  ffmpeg `lut3d`).
+- **`-distort perspective '<src coords> <dst coords>'`** - place a screenshot into a
+  device mockup.

package/bundled-references/programmatic-video.md

@@ -78,3 +78,25 @@ apply.
 `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).
+
+## Remotion's real renderer (from source) and the ideas to borrow
+
+Source study (Remotion License - concept only, no vendoring) shows Remotion is **not**
+the base64-PNG pipe we lump with Revideo/Motion Canvas: it drives headless Chromium
+over CDP, captures frames via **shared memory**, and encodes with a **per-platform
+native Rust sidecar that statically links FFmpeg** (a long-running streaming process),
+plus a bundled `ffmpeg` for the final stitch. Borrowable ideas (improve our Part C):
+
+- **A readiness gate, not just a fake clock.** `delayRender()`/`continueRender()`: a
+  component declares async work pending and the renderer blocks the screenshot until
+  all handles clear, reporting **labeled** open handles on timeout. Add an explicit
+  readiness handshake (plus a per-frame `await document.fonts.ready`) to Part C so no
+  frame is captured before fonts/data/images are ready - prevents FOUT/half-loaded
+  frames.
+- **Tab-pool concurrency**: open N browser pages, each seeking a different frame in
+  parallel (frame range / N).
+- **Chunked parallel encode + seamless concat**: split the frame range, encode chunks
+  independently, concat without re-encode - throughput for long renders.
+- **Kept-open, LRU-cached source-video decoders**: for embedded video assets, keep the
+  decoder open and cache frames so repeated seeks to a timestamp are cheap (our flat
+  timeline currently punts this to raw ffmpeg `-ss`).

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

@@ -161,10 +161,28 @@ GPL = concept only):
   `blendMode` values on overlay clips: Porter-Duff (`Over, Under, In, Out, ATop, Copy,
   Matte`) + blends (`Multiply, Screen, Overlay, SoftLight, HardLight, ColorBurn,
   ColorDodge, Difference, Exclusion, Hue, Saturation, Color, Luminosity`).
-- **Xsheet tabular timing** (opentoonz/tahoma2d, BSD). An optional rows=frames /
-  columns=assets exposure grid (cells = a drawing exposed for N frames, with holds) -
-  an LLM- and spreadsheet-friendly way to author precise timing, convertible to this
-  JSON timeline.
+- **Xsheet tabular timing** (opentoonz/tahoma2d, **BSD - code reusable with
+  attribution, a direct port target**). An optional rows=frames / columns=assets
+  exposure grid (cells = a drawing exposed for N frames; a *hold* is the same cell
+  repeated). The source implements this (and more of our model than we first credited)
+  in `TXsheet` / `TXshCellColumn` (`std::vector<TXshCell> m_cells`) / `TXshCell`
+  (`{level, TFrameId}`) / `TFrameId` (`{frame, letter}`), plus the cell-op vocabulary
+  (`reverseCells, swingCells, stepCells, reframeCells, timeStretch`). It also backs, as
+  BSD code: the **decomposed transform channels** (`TStageObject::Channel` T_X/T_Y/
+  T_Angle/T_ScaleX/... each a keyframe curve, with parenting + `T_Path` follow-spline),
+  a **richer easing enum** (`TDoubleKeyframe::Type` = Constant / Linear / SpeedInOut /
+  EaseInOut / EaseInOutPercentage / Exponential / Expression / File), **nested
+  sub-xsheets** (`TXshChildLevel` = precomp), and a **node-graph fx schematic**
+  (`FxDag`/`TFx`). So the easing/transform/nested-clip/effect-graph extensions above
+  have a BSD implementation to port, not only GPL concept sources.
+- **Strip/effect model + full blend set** (blender VSE `Strip`, concept). The Video
+  Sequence Editor's `Strip` (input1/input2, effect strips CROSS/WIPE/GLOW/SPEED/
+  ADJUSTMENT/TEXT, a Photoshop-complete `StripBlendMode`) and **F-curve modifier stack**
+  (noise/cycles/limits/stepped) + **drivers** (property-driven channels) are strong
+  concept borrows for overlay/effect clips.
+- **OTIO interchange** (kdenlive, concept). Document a mapping to OpenTimelineIO (the
+  ASWF-standard timeline interchange): gap=blank, stack=track, externalReference=asset
+  src - so the model can round-trip with real NLEs.
 - **Optional node-graph "effect graph"** (Natron, concept) for branched layered effects
   (mask -> blur -> merge) that a linear track can't express - heavy; a documented
   escape hatch, not the default.

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

@@ -25,7 +25,8 @@ sequenced, scroll-driven work.
 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
+  .from(".hero p",  { y: 24, opacity: 0 }, "-=0.3")    // overlap previous by 0.3s
+  .from(".hero a",  { opacity: 0 }, "<");              // "<"/">" = start/end of prev tween
 gsap.from(".card", {
   scrollTrigger: { trigger: ".card", start: "top 80%", once: true },
   y: 32, opacity: 0, stagger: 0.08,
@@ -35,6 +36,10 @@ gsap.from(".card", {
 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`.
+*Source note:* the `0.6`/`power3.out` above are our **house** defaults, not GSAP's
+(its own tween defaults are `0.5`/`power1.out` = quad); don't attribute them to GSAP.
+Parameterized ease strings — `"elastic.out(1,0.5)"`, `"back.out(1.7)"`,
+`"steps(12)"` — author a bespoke curve as a string.
 **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.
 
@@ -45,13 +50,17 @@ 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 });
+inView(".card", (el) => { animate(el, { opacity: 1, y: 0 }); }, { amount: "some" });
+// inView idiom is amount:"some"|"all" (a number works too) + margin (→ rootMargin)
 // 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.
+wrapper — our preferred engine when a dependency is acceptable. `motion/mini` is a
+WAAPI-only subset for the smallest payload. Spring also takes a **designer mode**
+`{ visualDuration, bounce }` (settle-time + bounciness, SwiftUI-style) instead of raw
+`stiffness/damping` — expose that to non-engineers (see the Spring pattern below).
 
 ### anime.js (juliangarnier/anime) — v4
 Small, elegant timeline/stagger/easing lib. V4 is ESM tree-shakable.
@@ -61,9 +70,14 @@ animate(".square", {
   x: 320, rotate: { from: -180 }, duration: 1250,
   delay: stagger(65, { from: "center" }), ease: "inOutQuint",
 });
+// 2D ripple from a grid cell (v4): delay: stagger(60, { grid: [cols, rows], from: "center" })
 ```
-**License: MIT.** **Reach for it when:** you want expressive staggers/keyframes
-lighter than GSAP and don't need ScrollTrigger-grade scroll control.
+**License: MIT** (v4: ESM, per-feature export subpaths — `animejs`, `animejs/stagger`,
+…; exports `animate, stagger, createTimeline, createTimer, createSpring, onScroll`,
+`eases/utils/svg/text`). **Reach for it when:** you want expressive staggers/keyframes
+lighter than GSAP and don't need ScrollTrigger-grade scroll control. Stagger vocabulary
+is rich: `from:'first'|'center'|'last'|'random'|index`, `grid:[x,y]`, `axis`,
+`reversed`, and an `ease` (even a spring) across the stagger.
 
 ### lottie-web (airbnb/lottie-web)
 Plays **Lottie JSON** (vector animations exported from After Effects via Bodymovin)
@@ -75,10 +89,16 @@ const anim = lottie.loadAnimation({
 });
 anim.playSegments([0, 60], true);          // play part of the timeline
 anim.setSpeed(1); anim.pause();
+lottie.freeze();                           // GLOBAL pause of every instance (tab hidden)
 ```
 **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.
+Default to `renderer: "svg"`; switch to `canvas` for heavy/many-layer files. For a
+small payload load the **`lottie_light`** build (SVG-only, no expressions). Perf/sync
+hooks worth using: `progressiveLoad`, `setSubframe(false)`, and the fine-grained events
+`enterFrame`/`loopComplete`/`segmentStart`. `freeze()/unfreeze()` are **global**
+(all instances); per-instance use `pause`/`goToAndStop`. No built-in reduced-motion —
+gate it yourself.
 
 ### rlottie (Samsung/rlottie)
 Native (C++) Lottie renderer — the runtime behind Lottie on native/embedded (not a
@@ -117,20 +137,26 @@ Animate-on-scroll via HTML data-attributes + a prebuilt CSS set.
      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.
+**License: MIT.** **Correction (source-verified, v3.0.0-beta.6):** this release does
+**not** use IntersectionObserver — it is classic **scroll + `lodash.throttle`**
+(`throttleDelay:99`); the only observer is a MutationObserver for auto-refresh on DOM
+injection. So copy its attribute *vocabulary* (`fade-up`, `once`, per-element
+delay/offset/anchor-placement), but do **not** credit it for observer efficiency — our
+hand-rolled reveal (§2) with a real IntersectionObserver is the better engine.
+**Reach for it when:** a no-JS-authoring team wants declarative scroll reveals fast.
 
 ### 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).
+**License: GPL-3.0 — flag it** (source-verified; the repo also ships paid
+`LIMITED`/`UNLIMITED_COMMERCIAL_LICENSE.md` with a Stripe link — a paid escape from
+copyleft). Do **not** bundle into proprietary/client output; reimplement the ~20-line
+effect yourself (or buy the commercial license). It also has **zero** reduced-motion
+handling (grep-confirmed) — you must gate it. **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.
@@ -143,6 +169,27 @@ await tsParticles.load({ id: "tsparticles", options: {
 **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.
+Source notes: v3+ `load()` takes **one object** `{ id, element?, options?, url? }`
+(positional form gone); 22 presets (`confetti`/`fireworks`/`snow`/`stars`/`links`/…)
+are one-line `preset:` strings; ship the **slim** bundle + only the `@tsparticles/*`
+feature packages you use. It also ships CLI scaffolders (`npm create tsparticles@latest`,
+`create-confetti`) and an **MCP server** — precedent for an agent-driven particle config.
+(Legacy origin: `particles.js` v2 — single-file, unmaintained, snake_case schema; use
+tsparticles instead, which bundles a `pjs` compat shim.)
+
+### mojs (@mojs/core)
+Motion-graphics toolbelt for the web — the one lib here built for **celebratory point
+bursts / success micro-interactions** (likes, add-to-cart, CTA confirm), a genuine gap
+the others don't fill. Actively maintained.
+```js
+import { Burst, Shape } from "@mojs/core";
+new Burst({ left: x, top: y, count: 8, radius: { 0: 60 },
+  children: { shape: "circle", fill: "#e94560", duration: 700 } }).play();
+```
+**License: MIT.** Also `ShapeSwirl`, `Html` (tween real DOM), `Timeline`, `stagger`,
+custom eases via `easing.path("M0,100 ...")` / `easing.bezier()`. **Reach for it when:**
+a discrete interaction deserves a tactile burst — keep it to a single gesture, gate on
+reduced-motion.
 
 ### rive (rive-app/rive-runtime)
 Interactive vector animations driven by **state machines** (inputs → states), not
@@ -161,23 +208,32 @@ drives animation state) — interactive mascots, animated toggles. Heavier workf
 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
+// type: delayed|sync|async|nsync|oneByOne|scenario|scenario-sync ; start: inViewport|manual|autostart
+v.setFrameProgress(0.5);   // scrub draw 0..1 (drive from scroll); play(-1) rewinds
 ```
-**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
+**License: MIT.** Timing fns are statics (`Vivus.EASE_OUT`, custom `function(x)`), set
+whole (`animTimingFunction`) or per-path (`pathTimingFunction`); per-path
+`data-delay/duration`, `data-vivus-ignore`; bundles `pathformer` (primitives → path).
+**Reach for it when:** a logo/icon/diagram should draw itself in — and, via
+`setFrameProgress(0..1)`, a **scroll-linked** draw-on (extends §2's one-shot draw). 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 */});
+const lenis = new Lenis({ autoRaf: true });     // DEFAULT is autoRaf:false → drive lenis.raf(t) yourself
+lenis.on("scroll", (e) => {/* e is the whole Lenis instance: e.scroll/.velocity/.progress/.direction */});
 ```
 **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.
+ScrollTrigger). **Source-verified defaults:** `lerp` is `0.1` (not 0.075 — that's
+`syncTouchLerp`), `autoRaf` defaults **false**, and `respectReducedMotion` is a
+first-class option (defaults true, falls back to native scroll via matchMedia).
+Attribute opt-outs: `data-lenis-prevent[-vertical|-horizontal]`. Accessibility caveat:
+keep `respectReducedMotion` on; never trap scroll in a way that breaks keyboard/anchor
+jumps.
 
 ### barba.js (barbajs/barba)
 SPA-style page transitions over MPAs: intercepts navigation, animates the old
@@ -203,6 +259,11 @@ 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.
+**Source-verified presets** (`tension`/`friction`[/`mass`]): default `{170,26}`,
+`gentle {120,14}`, `wobbly {180,12}`, `stiff {210,20}`, `slow {280,60}`,
+`molasses {280,120}`. The `AnimationConfig` also exposes a **designer-friendly**
+vocabulary — `frequency` + `damping(ratio)` (tension/friction derived from them),
+plus `clamp`, `bounce`, `decay` — prefer these when writing a config for non-engineers.
 
 ### animate.css (animate-css/animate.css)
 Prebuilt CSS keyframe classes (`animate__animated animate__fadeInUp`).
@@ -211,9 +272,20 @@ Prebuilt CSS keyframe classes (`animate__animated animate__fadeInUp`).
 ```
 **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.
+the keyframe recipes (`fadeInUp`, the `back_*` entrance/exit family, durations, timing)
+are fine to **reimplement** yourself. Two patterns worth copying wholesale: its
+**3-custom-prop timing system** (`--animate-duration` / `--animate-delay` /
+`--animate-repeat` + `calc()` utility multipliers) and its built-in **reduced-motion /
+print kill-switch** (collapses to 1ms and forces `*Out` animations to opacity 0 so
+content never sticks hidden). **Reach for the patterns when:** you want a quick
+named-entrance vocabulary — but author your own keyframes to stay license-clean.
+
+### Out of scope — pixijs (pixijs/pixijs)
+A WebGL/WebGPU **2D renderer**, not an animation engine: it ships no tween/easing (its
+`Ticker` gives only `deltaTime`). The particle/shader libs build *on* it; for standard
+DOM/CSS marketing motion it's out of scope — reach for it only for a heavy custom
+canvas scene, and bring your own tween (GSAP/Motion). (Notable: it ships 26 first-party
+`SKILL.md` agent skills — precedent for a library shipping its own skills.)
 
 ### Category O (offline / desktop, NOT web)
 - **synfig** (synfig/synfig) — desktop 2D vector animation studio. **GPL-3.0.**
@@ -236,14 +308,28 @@ Default to expressive ease-out curves, never browser defaults (`ease`, `linear`,
 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.**
+*Custom eases as data:* when a bespoke curve is needed, author it as data rather than
+code — GSAP parameterized strings (`"back.out(1.7)"`), mojs `easing.path()`/`bezier()`,
+vivus custom `function(x)`, or a popmotion-style `mirror/reverse` of a base ease. Store
+the curve with the motion spec (see Theatre.js data model below).
 
 ### 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`).
+For configs a non-engineer will touch, prefer the **designer vocabulary** both engines
+expose — Motion `{ visualDuration, bounce }`, react-spring `frequency` +
+`damping(ratio)` (settle-time + bounciness), rather than raw stiffness/damping.
 Libs: Motion `spring`, react-spring, GSAP (via plugins). **DM;** light touch on LP
 (mostly micro-interactions).
 
+### Burst / success micro-interaction
+A discrete gesture (like, add-to-cart, CTA confirm) earns a one-shot radial burst from
+the click point — one shape stamped into N transformed copies with an opacity ramp.
+Lib: mojs `Burst` (or a hand-rolled radial-stamp, same idea as the Lottie Repeater in
+[generative visuals](generative-visuals.md)). One gesture only; gate on reduced-motion.
+**LP (primary CTA) + DM.**
+
 ### 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`
@@ -349,7 +435,10 @@ illustration when a designer supplies the JSON.
 | auto-animate | MIT | |
 | AOS | MIT | |
 | typed.js | **GPL** | **Flag — don't bundle in proprietary output; reimplement.** |
-| tsparticles | MIT | |
+| tsparticles | MIT | v3+ single-object `load()`; ships CLI scaffolders + an MCP server. |
+| particles.js | MIT | Legacy v2, unmaintained — use tsparticles (`pjs` compat). |
+| mojs (@mojs/core) | MIT | Celebratory point bursts / success micro-interactions. |
+| pixijs | MIT | WebGL 2D **renderer**, no tween — out of scope for DOM motion. |
 | rive-runtime | MIT | Web runtime is `@rive-app/canvas`. |
 | vivus | MIT | |
 | lenis | MIT | |
@@ -371,9 +460,10 @@ state**, replayed by a tiny headless runtime (`@theatre/core`) against three.js,
 HTML/SVG, or any JS variable. The borrowable pattern is the **declarative keyframe
 document**, not the editor: store motion as JSON - a `sequence` with `length` +
 `subUnitsPerUnit` (an fps snap-grid) -> **tracks keyed by property path** ->
-**keyframes** each carrying `{ position, value, handles:[lx,ly,rx,ry],
-type:'bezier'|'hold' }` (per-keyframe bezier handles = per-segment easing baked into
-data; `value` may be non-numeric). Playback mirrors CSS: `play({ iterationCount,
+**keyframes** each carrying `{ id, position, value, handles:[lx,ly,rx,ry],
+connectedRight:boolean, type?:'bezier'|'hold' }` (per-keyframe bezier handles =
+per-segment easing baked into data; `type` is optional, defaults bezier; `value` may be
+non-numeric). Playback mirrors CSS: `play({ iterationCount,
 range, rate, direction:'alternateReverse' })`. Author a brand motion once, commit the
 JSON as a reusable asset, replay it deterministically with no editor shipped - the
 authoring story for `maggie-design-motion` (keep the motion *spec* as data, not
@@ -395,4 +485,9 @@ hero as `inputs -> conditions -> states` - declare inputs (`hovered:bool`,
 `scroll:0..1`, `clicked:trigger`), bind DOM events to them, and switch CSS/WAAPI/GSAP
 timelines by state rather than scripting each handler; a number input + interpolation
 gives scroll-linked response, random-picked idle transitions give a "living" element.
-(Rive's own MIT player is also a legitimate option.)
+(Rive's own MIT player is also a legitimate option.) Source-verified, the model is
+richer than the sketch above: any input source maps onto one **unified listener bus**
+(pointer/scroll/keyboard/gamepad/text/focus), transitions can be guarded by **app data**
+via **ViewModel data-binding conditions** (not just events), comparator ops are a full
+enum (`eq/neq/lt/gt/lte/gte`), and nested state machines compose — so "driven by data,
+not handlers" is the portable lesson for a browser reimplementation.

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

@@ -2,7 +2,7 @@
 name: maggie-image
 description: Process marketing images - resize and fit to channel/OG sizes, convert to WebP/AVIF, make favicon and OG-image sets, strip metadata, compress, optimize and render SVG, and build contact-sheet montages. A recipe generator over ImageMagick (primary) with dedicated tools (svgo/resvg/cwebp/avifenc/pngquant) used when installed. Use when the user wants to resize, convert, optimize, favicon, watermark, or batch-process images for a site or social post.
 metadata:
-  version: 0.1.2
+  version: 0.1.4
 ---
 
 # Maggie Image
@@ -53,12 +53,16 @@ maggie tool maggie_image.py --run strip --input photo.jpg --output photo.jpg
 maggie tool maggie_image.py --run compress --input big.jpg --output small.jpg --quality 82
 maggie tool maggie_image.py svgo --input logo.svg --output logo.min.svg --multipass
 maggie tool maggie_image.py svg2png --input logo.svg --output logo.png --width 512
+maggie tool maggie_image.py svg-query --input logo.svg                 # ids+bounds before --id slicing
+maggie tool maggie_image.py svg-export --input in.svg --output flat.svg --type svg \
+  --actions "select-all;object-to-path;vacuum-defs"                    # clean+flatten in one call
 maggie tool maggie_image.py --run montage --inputs a.png b.png c.png --output sheet.jpg --tile 3x
 maggie tool maggie_image.py presets
 ```
 
 Subcommands: `resize`, `social`, `webp`, `avif`, `favicon`, `strip`, `compress`,
-`svgo`, `svg2png`, `svg-export` (Inkscape: PDF/EPS, text-to-path, per-id slicing),
+`svgo`, `svg2png`, `svg-export` (Inkscape: PDF/EPS, text-to-path, per-id slicing, or
+`--actions` verb pipeline), `svg-query` (element ids + bounding boxes),
 `composite` (blend-mode layering), `look` (named style presets: sepia/duotone/
 posterize/vignette/...), `montage`, `presets`. `--run` (before the subcommand)
 executes when the tool is present; otherwise the command is printed for review.