@topy-ai/maggie 0.8.16 → 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.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
+目前 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.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.
+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/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`:

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.3
+  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.

package/bundled-tools/clis/maggie_image.py

@@ -10,7 +10,7 @@ and are generate-only until it is installed. Web-delivery quality defaults follo
 sharp/squoosh (JPEG/WebP ~80, AVIF ~50); OG/social are cover-cropped, logos pad.
 
 Subcommands: resize, social, webp, avif, favicon, strip, compress, svgo, svg2png,
-svg-export, composite, look, montage, presets.
+svg-export, svg-query, composite, look, montage, presets.
 """
 import argparse
 import shlex
@@ -163,6 +163,14 @@ def c_svg_export(a):
     """Inkscape headless export - fills the gaps resvg/ImageMagick can't: text-to-path
     font outlining, PDF/EPS for print, and per-id slicing. GPL app, invoked at arm's
     length (like ImageMagick)."""
+    # Actions pipeline: run an ordered verb list in one invocation (clean+flatten+export
+    # as a single call). `inkscape --action-list` prints every verb. Arm's-length (GPL).
+    if a.actions:
+        verbs = a.actions
+        if "export-filename" not in verbs and "export-do" not in verbs:
+            verbs = f"{verbs};export-filename:{a.output};export-type:{a.type};export-do"
+        print("# Inkscape actions pipeline: run an ordered verb list in one process.")
+        return emit(["inkscape", a.input, f"--actions={verbs}"], a.run, "inkscape")
     args = ["inkscape", a.input, f"--export-type={a.type}", f"--export-filename={a.output}"]
     if a.width:
         args.append(f"--export-width={a.width}")
@@ -182,6 +190,18 @@ def c_svg_export(a):
     return emit(args, a.run, "inkscape")
 
 
+def c_svg_query(a):
+    """Query an SVG's element ids and bounding boxes (Inkscape, arm's-length). Use the
+    output to build a correct --export-id slice list before slicing."""
+    if a.id:
+        args = ["inkscape", a.input, f"--query-id={a.id}",
+                "--query-x", "--query-y", "--query-width", "--query-height"]
+    else:
+        args = ["inkscape", a.input, "--query-all"]  # id,x,y,w,h per object (CSV)
+    print("# Inkscape geometry query: discover ids/bounds before --export-id slicing.")
+    return emit(args, a.run, "inkscape")
+
+
 def c_composite(a):
     """Layer an overlay onto a base with a blend mode (Pinta/Natron vocabulary ->
     ImageMagick -compose). Modes: Over, Multiply, Screen, Overlay, Darken, Lighten,
@@ -285,8 +305,15 @@ def main(argv=None):
     se.add_argument("--area", choices=["drawing", "page"], default="drawing")
     se.add_argument("--id", help="export only this element/layer id")
     se.add_argument("--text-to-path", dest="text_to_path", action="store_true", help="outline fonts")
+    se.add_argument("--actions", help="run an ordered verb pipeline instead (e.g. "
+                    "'select-all;object-to-path;vacuum-defs'); auto-appends export verbs")
     se.add_argument("--background"); se.set_defaults(fn=c_svg_export)
 
+    sq = sub.add_parser("svg-query", help="query SVG element ids + bounding boxes (Inkscape)")
+    sq.add_argument("--input", required=True)
+    sq.add_argument("--id", help="query one id's x/y/w/h (default: --query-all for every object)")
+    sq.set_defaults(fn=c_svg_query)
+
     cp = sub.add_parser("composite", help="layer an overlay on a base with a blend mode")
     cp.add_argument("--base", required=True); cp.add_argument("--overlay", required=True)
     cp.add_argument("--output", required=True); cp.add_argument("--mode", default="Over")

package/package.json

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

package/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`:

package/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.