@topy-ai/maggie 0.8.17 → 0.8.19

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.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
+目前 npm 版本為 `0.8.19`,研究非 Q 設計 repo 所提供的**產品級 agent 介面**(MCP/skills/CLI)——即目標中「tools, MCP, skills, CLIs」這一維度,單靠檔案數無法涵蓋——寫入新的 `references/agent-native-design-surfaces.md`(tldraw 的 `search`+`exec` 畫布 MCP、Babylon.js WebMCP 雙 adapter、penpot/darktable/tsparticles 的 MCP 工具面、pixijs 的 router-skill 範式),並把具體 CLI 發現併入(svgo `--datauri`/`--precision`、whisperX 說話者分離/行寬旗標、editly 宣告式 spec),同時把 `docs/design-coverage-audit.md` 重寫為把**存在性**(檔案數)與**研究深度**(code/surface/API)當成兩條獨立軸——更正先前把「工作樹存在」與「代碼級研究過」混為一談的問題。`0.8.18` 把「每個非 Q repo 都在代碼級研究過」從斷言變成可查證的證據:`docs/design-coverage-audit.md` 重寫為逐 repo 的檔案數(工作樹大小),涵蓋全部 81 個非 Q 設計 repo(K-R),每個都抽查源碼深度,證明都是完整 checkout 而非 sparse stub(唯一的 stub,inkscape GitHub,由 GitLab clone 解決;blender 缺的是 git-LFS 二進位筆刷美術素材,屬內容非程式碼)。並驗證先前僅概念級借鑑的 O 類引擎源碼(synfig/friction/Natron/wick/rlottie),更正資料模型(synfig 緩動曲線為 `HALT` 非 `EASE`;wick 欄位為 `animationType` 非 `playbackMode`;rlottie 結構為 `Trim`/`Repeater`/`Mask` 非 `LOT*Data`)並把 net-new 併入 `video-timeline-model.md`。`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.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.
+This package is `0.8.19` — studies the product agent-surfaces (MCP/skills/CLI) that non-Q design repos ship (the "tools, MCP, skills, CLIs" dimension file counts didn't cover) in a new `references/agent-native-design-surfaces.md` (tldraw `search`+`exec` canvas MCP, Babylon.js WebMCP dual-adapter, penpot/darktable/tsparticles MCP, pixijs router-skill template), folds CLI findings in (svgo `--datauri`/`--precision`, whisperX diarization flags, editly declarative spec), and rewrites `docs/design-coverage-audit.md` to track existence (file count) vs study depth (code/surface/API) as separate axes. `0.8.18` — turns the "every non-Q repo studied at the codebase level" claim into measured evidence: `docs/design-coverage-audit.md` is rewritten with a per-repo file count for all 81 non-Q design repos (K-R), proving full checkouts not sparse stubs (inkscape stub resolved by a GitLab clone; blender's absent files are git-LFS binary brush art, not code). Also verifies the O-category engine source (synfig/friction/Natron/wick/rlottie) earlier borrowed at concept level, correcting the data model (synfig ease is `HALT`; wick field `animationType`; rlottie structs `Trim`/`Repeater`/`Mask`) and adding net-new to `video-timeline-model.md`. `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/agent-native-design-surfaces.md

@@ -0,0 +1,114 @@
+# Agent-native design surfaces (how design OSS exposes itself to agents)
+
+Borrowable **patterns** (not code) for building our own agent surfaces — MCP tools, agent
+skills, and CLIs — distilled from open-source design/animation projects that already
+expose themselves to LLM agents. This is the "tools / MCP / skills / CLIs" dimension of
+the reference library (categories L–R), studied at the product-surface level. Pairs with the
+`maggie-assistant-tools` skill (our tool/MCP/skill boundary) and
+[design-editor-patterns](design-editor-patterns.md).
+
+**Scope note.** Most `skills/` and `mcp` paths in these repos are *repo-maintenance*
+tooling (nx tasks, PR bots, speckit, release scripts) — not borrowable. The patterns
+below are the genuine **product** surfaces: a library making its own document/API
+operable by an agent.
+
+## MCP: exposing a live document to an agent
+
+### The `search` + `exec` collapse (tldraw, strongest borrow)
+tldraw's entire canvas mutation surface is **two public tools**, not dozens of narrow ones:
+- **`search`** — query the extracted Editor-API spec (self-describing API discovery); the
+  query runs sandboxed against the spec object so the agent finds the method it needs.
+- **`exec`** — run JavaScript against the live `editor` instance through a pending-request
+  callback bridge, returning the result within a **bounded wait** (≈4–8s) or "still
+  executing." An optional `canvasId` continues an existing doc vs. starting a new one.
+Hidden app-only tools (`_exec_callback`, `_get_canvas_state`, `read/save_checkpoint`) let
+the widget resolve execs and persist user edits. The doc ships as an **MCP-UI resource**
+(`ui://…`) with CSP `resourceDomains`/`connectDomains` allow-lists, distributed via the
+official `server.json` registry schema. **Borrow:** for an agent-operable design doc,
+prefer *discover-the-API + run-code-against-the-live-doc* over hand-writing many tools, and
+serve the doc itself as an interactive UI widget with checkpointed state.
+
+### Dual-adapter + writer arbitration (Babylon.js WebMCP)
+One set of **transport-neutral domain operations** behind **two thin adapters**: a normal
+stdio MCP server (external clients) and a **WebMCP** adapter (`document.modelContext`) so a
+browser agent drives the *live editor page* with no separate session. A **writer-
+arbitration state machine** keeps them safe: a connected legacy/human session owns all
+mutations; agent reads stay allowed, agent mutations are rejected with a clear message
+until the human disconnects. Every mutation is transactional (serialize live doc → apply
+in shared core → diff back → single undo entry). The stdio fallback uses a **session
+bridge**: a local HTTP+SSE server keyed by `Map<sessionId, docName>`, `GET
+/session/:id/events` (SSE push) + `POST /session/:id/...` (push user edits back), the
+create tool returning a paste-able session URL. **Borrow:** define our design/marketing
+operations once, surface them through both an MCP server and a live-page bridge, with one
+writer rule so human + agent never clobber the same document.
+
+### Self-describing bootstrap tools (penpot)
+A general `execute_code({code, sessionId})` (JS in an in-app plugin over WebSocket) stays
+usable because two cheap tools front-load *how to drive it*: **`high_level_overview`**
+("read once, don't call again") and **`*_api_info`** (API docs on demand). Plus
+`export_shape`, `import_image`, `import_penpot_file`. **Borrow:** pair a general exec tool
+with a self-describing overview + on-demand API-info tool instead of many narrow tools.
+
+### Generate → diagnose → suggest-deps (tsparticles)
+Config generation as a triad: **`generate_code`** (NL → ready-to-run config, deterministic
+keyword→bundle matching, framework-aware), **`diagnose_issues`** (a self-lint over a config
+for correctness + perf), **`suggest_plugins`/`list_packages`/`get_package_info`** (which
+deps a given options object needs). Resources expose the catalog
+(`tsparticles://packages|bundles|options/guide`). **Borrow:** for any config-driven asset
+(a marketing animation/effect), use deterministic selection over LLM guesswork and give the
+agent a `diagnose` tool to self-check — generate, then lint, then resolve deps.
+
+### Params-as-data + reusable style presets (darktable)
+~24 MCP tools around a **non-destructive, params-as-data** model: `decode_params`/
+`encode_params` (hex op blob ↔ named fields), `render` (develop through the pipeline),
+**`image_stats`** (per-channel min/max/mean/percentiles — a cheap numeric feedback signal
+an agent can read back), `get_history`/`reset_history`, and **styles**
+(`save_style`/`apply_style`/`list_styles` — save an edit stack once, apply to many assets).
+**Borrow:** model an image edit as a replayable param stack, expose `image_stats` as agent
+feedback, and make "styles" (named reusable edit recipes) first-class — maps directly onto
+batch brand-image processing (see the darktable edit-recipe in
+[design-editor-patterns](design-editor-patterns.md)).
+
+## Skills: packaging a toolkit's usage for agents
+
+### Router skill + keyword-rich leaves + llms.txt fallback (pixijs)
+27 skills structured as **one router** (`SKILL.md` with a dense trigger-keyword
+`description` and a routing table) dispatching to **fine-grained leaf skills** (one per
+surface: `pixijs-events`, `-performance`, `-filters`, `-assets`, …), each with its own
+heavy trigger-keyword frontmatter + a "Quick Start" code block, and an explicit
+**fallback to `llms.txt`** (WebFetch the auto-generated current API index) for anything no
+leaf covers. **Borrow:** progressive disclosure — a router + one leaf per surface + an
+llms.txt escape hatch is the template for packaging our own toolkit's usage as skills.
+
+### Mental-model-first + sandbox-safe quick start (pts)
+A single creative-coding skill that leads with a **3-noun mental model** ("Space = paper,
+Form = pencil, Pt/Group = ideas"), then a **no-bundler sandbox-safe quick start**
+(`Pts.quickStart` via ESM, works on a locked-down page), then the package tour. **Borrow:**
+open a library skill with a tiny mental model + a copy-paste quick start that runs in a
+restricted sandbox, before any API list.
+
+## CLIs: command surfaces worth matching
+
+- **svgo** (we already wrap it) — plugin architecture (`preset-default` = an ordered,
+  configurable plugin list). Flags our wrapper should consider: **`--datauri`**
+  (emit an embeddable data-URI), **`--multipass`**, **`--precision`**, **`--show-plugins`**
+  (enumerate plugins for an agent), recursive folder (`-r`/`-f`) + `--exclude`.
+- **editly** — a declarative NLE spec (`editSpec` JSON5) with CLI↔field parity:
+  `clips[] → layers[] → transitions`, a fixed **layer-type vocabulary** (`video, audio,
+  image, image-overlay, title, subtitle, news-title, slide-in-text, fill-color,
+  radial/linear-gradient, canvas, fabric, gl`), auto letterbox/fps-convert, auto
+  audio crossfade/duck/normalize, and `canvas`/`fabric`/`gl` layers taking custom JS/
+  shaders. This is the shape for an **agent-authored short-video/promo recipe** (1:1 /
+  9:16 / 16:9 presets fall out) — see [video-timeline-model](video-timeline-model.md).
+- **whisperX** — beyond plain whisper: `--diarize` (+`--min/max_speakers`,
+  `--diarize_model`, `--speaker_embeddings`), word/char alignment (`--align_model`,
+  `--return_char_alignments`, `--interpolate_method`), and subtitle line control
+  (`--highlight_words`, `--max_line_width`, `--max_line_count`) — the layer that turns a
+  caption into styled, karaoke-timed, speaker-split social-video subtitles. See
+  [captions-transcription](captions-transcription.md).
+
+## Licensing
+Patterns/architecture only (adopt the idea, write our own code): Babylon.js (Apache-2.0),
+tldraw (custom), penpot (MPL), tsparticles (MIT), pixijs (MIT), pts (Apache-2.0),
+darktable (GPL, invoke binary at arm's length). editly (MIT), svgo (MIT), whisperX (BSD)
+are freely borrowable as ideas; we reimplement rather than vendor.

package/bundled-references/captions-transcription.md

@@ -58,4 +58,18 @@ The core CLI already does what we previously routed to whisperX or post-processi
 - `--task translate` (foreign audio -> English subs), `--clip_timestamps` (only given
   ranges).
 
+## When whisperX still wins (source-verified CLI surface)
+
+Core whisper covers word timestamps + highlight; reach for **whisperX** (BSD) when you
+need **speaker diarization** or tighter alignment. Its extra flags, read from source:
+`--diarize` (+ `--min_speakers`/`--max_speakers`, `--diarize_model`,
+`--speaker_embeddings`, `--hf_token`), forced alignment (`--align_model`, `--no_align`,
+`--return_char_alignments`, `--interpolate_method`), VAD tuning (`--vad_method`,
+`--vad_onset`/`--vad_offset`, `--chunk_size`), and subtitle line control
+(`--highlight_words`, `--max_line_width`, `--max_line_count`, `--segment_resolution`),
+plus `--suppress_numerals` and `--hotwords`. Use diarization + line-width control to turn
+a raw transcript into **speaker-split, karaoke-timed, safe-area-fit** social-video
+subtitles. For the agent-surface view of this (and editly/svgo), see
+[agent-native design surfaces](agent-native-design-surfaces.md).
+
 See `maggie-video` for the subcommands and the burn-in / soft-mux / compile options.

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

@@ -72,6 +72,15 @@ pose/depth/segmentation) and IP-Adapter (reference image, style/composition tran
 The plugin-over-backend boundary (editor model stays; AI is a swappable backend)
 mirrors the arm's-length posture in [AI media generation](ai-media-generation.md).
 
+## Agent surfaces (MCP/skills/CLI these editors expose)
+
+For how these editors expose their *live document* to an agent — tldraw's `search`+`exec`
+canvas MCP, penpot's `execute_code` + `high_level_overview` bootstrap tools, darktable's
+params-as-data MCP with reusable style presets, Babylon.js WebMCP dual-adapter + writer
+arbitration, and the pixijs router-skill template — see
+[agent-native design surfaces](agent-native-design-surfaces.md). That reference is the
+"tools / MCP / skills / CLIs" dimension of the design reference library.
+
 ## Licensing
 
 Invoke binaries at arm's length (never vendor): inkscape, darktable (GPL). Concepts

package/bundled-references/image-recipes.md

@@ -57,6 +57,8 @@ pngquant --quality 60-82 --strip --output out.png in.png            # lossy PNG
 
 ```bash
 svgo --multipass -i in.svg -o out.svg      # keeps viewBox + title (responsive + a11y). If svgo absent, leave the SVG alone - never rasterize as a substitute.
+svgo --datauri base64 -p 2 -i icon.svg -o icon.txt  # embeddable data: URI (inline an icon); -p = coordinate precision
+# svgo is an ordered plugin pipeline (preset-default); `svgo --show-plugins` lists them, folder mode is `-f DIR -r --exclude PAT`
 resvg -w 512 in.svg out.png                # best-fidelity SVG -> PNG (or rsvg-convert -w 512); IM fallback (-background none -density 384) is lower fidelity
 ```
 

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

@@ -91,7 +91,14 @@ Compile the model to one `filter_complex`:
 - **output:** `-c:v libx264 -r fps -pix_fmt yuv420p -c:a aac out.mp4`.
 
 `mifi/editly` (MIT) and `Zulko/moviepy` (MIT) are working prior art that this JSON
-shape renders through ffmpeg without any GPL engine.
+shape renders through ffmpeg without any GPL engine. editly's `editSpec` (source-verified)
+is the closest match to adopt: `clips[] -> layers[] -> transitions` with a **fixed
+layer-type vocabulary** (`video, audio, image, image-overlay, title, subtitle, news-title,
+slide-in-text, fill-color, radial/linear-gradient, canvas, fabric, gl`), top-level
+`defaults.transition`, auto letterbox/fps-convert and auto audio crossfade/duck/normalize,
+and `canvas`/`fabric`/`gl` layers that take custom JS/shaders. An agent authors this spec
+directly; 1:1 / 9:16 / 16:9 presets fall out of `width/height`. See
+[agent-native design surfaces](agent-native-design-surfaces.md) for the CLI/spec surface.
 
 ### maggie_video.py compile
 
@@ -137,30 +144,69 @@ Concepts to grow the model (adopt the data shape / vocabulary; code only from th
 MIT/BSD sources - rlottie MIT, opentoonz/tahoma2d BSD; synfig/friction/wick/Natron
 GPL = concept only):
 
-- **Richer keyframe easing** (synfig). Extend `{t, v, ease}` with: **per-side ease**
-  (`easeIn` != `easeOut`), **`clamped`** (auto-smooth that won't overshoot the keyed
-  value), **`hold`/`constant`**, and optional **TCB** `{tension, continuity, bias}`.
-  Add **`fullRotations`** on a rotation keyframe (wick) to control spin count/direction
-  rather than shortest-path. These precompute to per-frame values for ffmpeg and map to
-  CSS/Lottie beziers. (compile currently interpolates linearly; this is the target
-  vocabulary.)
-- **Lottie JSON as the companion vector-motion-graphics format** (rlottie, MIT). For
-  logo stings, animated icons and kinetic type, use Lottie (After-Effects/Figma
-  exportable, in-browser renderable via lottie-web) alongside the MLT/NLE shape. Borrow
-  its primitives: **Trim-path** (`start%/end%/offset` - the formal version of the
-  "draw a line on" trick in [design-motion production](design-motion-production.md)),
-  **Repeater** (N copies with a transform + opacity ramp), **track mattes**
-  (`Alpha/Luma`), **transform parenting**, and **time remap** (`tm`).
-- **Nested clips / precomps** (wick/lottie). A clip may hold its own timeline with a
-  playback mode (`loop | playOnce | single`) and be instanced - reusable lower-thirds,
-  intro/outro stingers; a composable alternative to the flat track list.
-- **Decomposed transform + animatable pivot** (friction). Split transform into
-  `pos / scale / rot / shear / pivot / opacity`, each its own keyframe curve, with a
-  **movable pivot** for correct scale/rotate around a moving anchor.
-- **Blend-mode / compositing vocabulary** (Natron `MergingFunctionEnum`). The allowed
-  `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`).
+- **Richer keyframe easing** (synfig, source-verified `synfig-core/src/synfig/
+  interpolation.h` + `waypoint.h`). A waypoint carries **two independent interpolation
+  enums** — `before` and `after` (so easeIn != easeOut is just two enums, not a special
+  case). The real `enum Interpolation` (a plain enum, not enum class) is `TCB,
+  CONSTANT, LINEAR, HALT, MANUAL, UNDEFINED, NIL, CLAMPED` — note the ease-in/out curve
+  is **`HALT`** (there is no `INTERPOLATION_EASE`), `CLAMPED` is the no-overshoot
+  auto-smooth, `CONSTANT` is hold. **TCB** is `{tension, continuity, bias}` **plus a
+  4th `temporal_tension`** (tension on the time axis, separate from spatial). Two
+  data-shape borrows: every waypoint field has a paired **`*_flag` boolean** (explicit
+  "overridden vs inherited-default" tracking — the model for optional per-keyframe
+  overrides), and **`NIL`** is the "unset, inherit the default" sentinel (distinct from
+  `UNDEFINED`). Add **`fullRotations`** on a rotation keyframe (wick,
+  `Tween.js:48` — integer N = number of full turns, sign = direction) to express
+  "spin 3x clockwise" without angle unwrapping. These precompute to per-frame values for
+  ffmpeg and map to CSS/Lottie beziers. (compile currently interpolates linearly; this
+  is the target vocabulary.)
+- **Lottie JSON as the companion vector-motion-graphics format** (rlottie, **MIT -
+  citable for code**; names verified in `src/lottie/lottiemodel.h`, which uses `model::`
+  classes, **not** the older `LOT*Data` names). For logo stings, animated icons and
+  kinetic type, use Lottie (After-Effects/Figma exportable, in-browser renderable via
+  lottie-web) alongside the MLT/NLE shape. The single most useful data-shape is the
+  uniform **`Property<T>`** wrapper with **`isStatic()`** - every animatable value is
+  either a constant or a keyframed track, queried the same way (adopt this as the base
+  of the JSON model). Borrow its primitives: **`Trim`** (`mStart/mEnd/mOffset` %, +
+  `TrimType{Simultaneously, Individually}` - the formal version of the "draw a line on"
+  trick in [design-motion production](design-motion-production.md)), **`Repeater`**
+  (`mCopies/mOffset` + a `Transform` with `mStartOpacity -> mEndOpacity` ramp across
+  copies, capped at 10000), **track mattes** `MatteType{None, Alpha, AlphaInv, Luma,
+  LumaInv}` (note the **inverted** variants), **`Mask`** (a *distinct* mechanism from
+  mattes: `Mode{None, Add, Subtract, Intersect, Difference}` + an invert flag),
+  **transform parenting**, **time remap** (`mTimeRemap`, "tm"), and the generative
+  primitives **`Polystar`** (`PolyType{Star, Polygon}`, one shape for both via inner/
+  outer radius+roundness), separate `GradientFill`/`GradientStroke`, and stroke `Dash`.
+- **Nested clips / precomps** (wick/lottie, verified `engine/src/base/Clip.js`). A
+  `Clip` owns its own `Wick.Timeline` (nestable sub-timelines) with an **`animationType`**
+  (the real field; values `'loop' | 'single' | 'playOnce'` from
+  `Wick.Clip.animationTypes` - *not* `playbackMode`, and ignore a stale "oneFrame" code
+  comment) and is instanced via a tracked `_clones` list - reusable lower-thirds,
+  intro/outro stingers; a composable alternative to the flat track list. Wick's tween
+  model is also worth copying: keys are **sparse** and interpolation is a static function
+  over two keys (`Tween.interpolate(a, b, playhead)`, `easingType` in
+  `none|in|out|in-out`), not baked per frame.
+- **Decomposed transform + animatable pivot** (friction, verified
+  `src/core/Animators/transformanimator.h` - a 3-level hierarchy
+  `BasicTransformAnimator -> AdvancedTransformAnimator -> BoxTransformAnimator`). Split
+  transform into `pos / scale / rot / shear / pivot / opacity`, each its own keyframe
+  curve (`QPointFAnimator`/`QrealAnimator`), with the **pivot itself an animated point**
+  kept separate from **shear** (most Lottie-style models have neither an animatable pivot
+  nor shear), and `setPivotFixedTransform` to move the pivot without disturbing the box.
+  Parenting is a first-class edge (`setParentTransformAnimator` + stored `mPostTransform`
+  matrix); grouped "is-animated" queries over a property subset back a JSON `animated:
+  bool` rollup.
+- **Blend-mode / compositing vocabulary** (Natron `MergingFunctionEnum`, verified
+  `Global/Enums.h` - 39 members, `eMergeATop = 0`). The allowed `blendMode` values on
+  overlay clips: Porter-Duff (`Over, Under, In, Out, ATop, Copy, Matte`) + the standard
+  blends (`Multiply, Screen, Overlay, SoftLight, HardLight, ColorBurn, ColorDodge,
+  Difference, Exclusion, Hue, Saturation, Color, Luminosity`) + a fuller set worth
+  adopting: `ConjointOver, DisjointOver, PinLight, Average, Divide, Plus, Minus, From,
+  Freeze, Reflect, GrainExtract, GrainMerge, Geometric, Hypot, Mask, Stencil, Max, Min,
+  XOR`. Natron models blend as a **per-node knob** on a Merge node with named inputs
+  (A/B + optional mask), not a flat per-layer z-order field - so for branched effects
+  treat blend as a property on a merge/group node (see the effect-graph escape hatch
+  below).
 - **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
@@ -175,6 +221,12 @@ GPL = concept only):
   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.
+- **Shared / linked parameters** (synfig exported ValueNodes, `canvas.h`
+  `add_value_node(node, id)`). A canvas holds **named (exported) value nodes**, and many
+  parameters reference the same node by id - one source of truth for a color, duration or
+  curve reused across clips. Borrow as a timeline-level **`defs` map keyed by id** with
+  properties referencing `{$ref: id}` (a brand accent or a shared ease authored once,
+  linked everywhere).
 - **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**

package/bundled-skills/maggie-assistant-tools/SKILL.md

@@ -99,6 +99,11 @@ consent**; they need `retentionDays`, `supportAccess` (`none` or
 `with-consent`) and `deleteOnAccountDeletion: true`. Keep approval tokens out
 of the stored thread text (they live with the model turn, see below).
 
+For agent-surface patterns borrowed from design/animation OSS (tldraw's `search`+`exec`
+canvas MCP, Babylon.js WebMCP dual-adapter + writer arbitration, penpot's self-describing
+bootstrap tools, darktable's params-as-data MCP, pixijs's router-skill template), see
+[agent-native design surfaces](../../references/agent-native-design-surfaces.md).
+
 ## Resources and prompts, not only tools
 
 An MCP server has two more surfaces worth exposing beyond tools:

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.4
+  version: 0.1.5
 ---
 
 # Maggie Image

package/bundled-tools/clis/maggie_image.py

@@ -123,7 +123,13 @@ def c_compress(a):
 
 
 def c_svgo(a):
-    args = ["svgo", "--multipass"] if a.multipass else ["svgo"]
+    args = ["svgo"]
+    if a.multipass:
+        args.append("--multipass")
+    if a.precision is not None:
+        args += ["-p", str(a.precision)]
+    if a.datauri:
+        args += ["--datauri", a.datauri]  # base64|enc|unenc -> embeddable data: URI
     args += ["-i", a.input, "-o", a.output]
     print("# svgo keeps viewBox and title by default (responsive + accessible).")
     if not shutil.which("svgo"):
@@ -288,7 +294,11 @@ def main(argv=None):
     co.add_argument("--quality", type=int, default=82); co.set_defaults(fn=c_compress)
 
     so = sub.add_parser("svgo", help="optimize an SVG (svgo)"); io(so)
-    so.add_argument("--multipass", action="store_true"); so.set_defaults(fn=c_svgo)
+    so.add_argument("--multipass", action="store_true")
+    so.add_argument("--precision", type=int, help="coordinate precision (fewer digits = smaller)")
+    so.add_argument("--datauri", choices=["base64", "enc", "unenc"],
+                    help="emit an embeddable data: URI instead of a file body")
+    so.set_defaults(fn=c_svgo)
     sp = sub.add_parser("svg2png", help="render SVG -> PNG (resvg)"); io(sp)
     sp.add_argument("--width", type=int); sp.add_argument("--background"); sp.set_defaults(fn=c_svg2png)
 

package/package.json

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

package/references/agent-native-design-surfaces.md

@@ -0,0 +1,114 @@
+# Agent-native design surfaces (how design OSS exposes itself to agents)
+
+Borrowable **patterns** (not code) for building our own agent surfaces — MCP tools, agent
+skills, and CLIs — distilled from open-source design/animation projects that already
+expose themselves to LLM agents. This is the "tools / MCP / skills / CLIs" dimension of
+the reference library (categories L–R), studied at the product-surface level. Pairs with the
+`maggie-assistant-tools` skill (our tool/MCP/skill boundary) and
+[design-editor-patterns](design-editor-patterns.md).
+
+**Scope note.** Most `skills/` and `mcp` paths in these repos are *repo-maintenance*
+tooling (nx tasks, PR bots, speckit, release scripts) — not borrowable. The patterns
+below are the genuine **product** surfaces: a library making its own document/API
+operable by an agent.
+
+## MCP: exposing a live document to an agent
+
+### The `search` + `exec` collapse (tldraw, strongest borrow)
+tldraw's entire canvas mutation surface is **two public tools**, not dozens of narrow ones:
+- **`search`** — query the extracted Editor-API spec (self-describing API discovery); the
+  query runs sandboxed against the spec object so the agent finds the method it needs.
+- **`exec`** — run JavaScript against the live `editor` instance through a pending-request
+  callback bridge, returning the result within a **bounded wait** (≈4–8s) or "still
+  executing." An optional `canvasId` continues an existing doc vs. starting a new one.
+Hidden app-only tools (`_exec_callback`, `_get_canvas_state`, `read/save_checkpoint`) let
+the widget resolve execs and persist user edits. The doc ships as an **MCP-UI resource**
+(`ui://…`) with CSP `resourceDomains`/`connectDomains` allow-lists, distributed via the
+official `server.json` registry schema. **Borrow:** for an agent-operable design doc,
+prefer *discover-the-API + run-code-against-the-live-doc* over hand-writing many tools, and
+serve the doc itself as an interactive UI widget with checkpointed state.
+
+### Dual-adapter + writer arbitration (Babylon.js WebMCP)
+One set of **transport-neutral domain operations** behind **two thin adapters**: a normal
+stdio MCP server (external clients) and a **WebMCP** adapter (`document.modelContext`) so a
+browser agent drives the *live editor page* with no separate session. A **writer-
+arbitration state machine** keeps them safe: a connected legacy/human session owns all
+mutations; agent reads stay allowed, agent mutations are rejected with a clear message
+until the human disconnects. Every mutation is transactional (serialize live doc → apply
+in shared core → diff back → single undo entry). The stdio fallback uses a **session
+bridge**: a local HTTP+SSE server keyed by `Map<sessionId, docName>`, `GET
+/session/:id/events` (SSE push) + `POST /session/:id/...` (push user edits back), the
+create tool returning a paste-able session URL. **Borrow:** define our design/marketing
+operations once, surface them through both an MCP server and a live-page bridge, with one
+writer rule so human + agent never clobber the same document.
+
+### Self-describing bootstrap tools (penpot)
+A general `execute_code({code, sessionId})` (JS in an in-app plugin over WebSocket) stays
+usable because two cheap tools front-load *how to drive it*: **`high_level_overview`**
+("read once, don't call again") and **`*_api_info`** (API docs on demand). Plus
+`export_shape`, `import_image`, `import_penpot_file`. **Borrow:** pair a general exec tool
+with a self-describing overview + on-demand API-info tool instead of many narrow tools.
+
+### Generate → diagnose → suggest-deps (tsparticles)
+Config generation as a triad: **`generate_code`** (NL → ready-to-run config, deterministic
+keyword→bundle matching, framework-aware), **`diagnose_issues`** (a self-lint over a config
+for correctness + perf), **`suggest_plugins`/`list_packages`/`get_package_info`** (which
+deps a given options object needs). Resources expose the catalog
+(`tsparticles://packages|bundles|options/guide`). **Borrow:** for any config-driven asset
+(a marketing animation/effect), use deterministic selection over LLM guesswork and give the
+agent a `diagnose` tool to self-check — generate, then lint, then resolve deps.
+
+### Params-as-data + reusable style presets (darktable)
+~24 MCP tools around a **non-destructive, params-as-data** model: `decode_params`/
+`encode_params` (hex op blob ↔ named fields), `render` (develop through the pipeline),
+**`image_stats`** (per-channel min/max/mean/percentiles — a cheap numeric feedback signal
+an agent can read back), `get_history`/`reset_history`, and **styles**
+(`save_style`/`apply_style`/`list_styles` — save an edit stack once, apply to many assets).
+**Borrow:** model an image edit as a replayable param stack, expose `image_stats` as agent
+feedback, and make "styles" (named reusable edit recipes) first-class — maps directly onto
+batch brand-image processing (see the darktable edit-recipe in
+[design-editor-patterns](design-editor-patterns.md)).
+
+## Skills: packaging a toolkit's usage for agents
+
+### Router skill + keyword-rich leaves + llms.txt fallback (pixijs)
+27 skills structured as **one router** (`SKILL.md` with a dense trigger-keyword
+`description` and a routing table) dispatching to **fine-grained leaf skills** (one per
+surface: `pixijs-events`, `-performance`, `-filters`, `-assets`, …), each with its own
+heavy trigger-keyword frontmatter + a "Quick Start" code block, and an explicit
+**fallback to `llms.txt`** (WebFetch the auto-generated current API index) for anything no
+leaf covers. **Borrow:** progressive disclosure — a router + one leaf per surface + an
+llms.txt escape hatch is the template for packaging our own toolkit's usage as skills.
+
+### Mental-model-first + sandbox-safe quick start (pts)
+A single creative-coding skill that leads with a **3-noun mental model** ("Space = paper,
+Form = pencil, Pt/Group = ideas"), then a **no-bundler sandbox-safe quick start**
+(`Pts.quickStart` via ESM, works on a locked-down page), then the package tour. **Borrow:**
+open a library skill with a tiny mental model + a copy-paste quick start that runs in a
+restricted sandbox, before any API list.
+
+## CLIs: command surfaces worth matching
+
+- **svgo** (we already wrap it) — plugin architecture (`preset-default` = an ordered,
+  configurable plugin list). Flags our wrapper should consider: **`--datauri`**
+  (emit an embeddable data-URI), **`--multipass`**, **`--precision`**, **`--show-plugins`**
+  (enumerate plugins for an agent), recursive folder (`-r`/`-f`) + `--exclude`.
+- **editly** — a declarative NLE spec (`editSpec` JSON5) with CLI↔field parity:
+  `clips[] → layers[] → transitions`, a fixed **layer-type vocabulary** (`video, audio,
+  image, image-overlay, title, subtitle, news-title, slide-in-text, fill-color,
+  radial/linear-gradient, canvas, fabric, gl`), auto letterbox/fps-convert, auto
+  audio crossfade/duck/normalize, and `canvas`/`fabric`/`gl` layers taking custom JS/
+  shaders. This is the shape for an **agent-authored short-video/promo recipe** (1:1 /
+  9:16 / 16:9 presets fall out) — see [video-timeline-model](video-timeline-model.md).
+- **whisperX** — beyond plain whisper: `--diarize` (+`--min/max_speakers`,
+  `--diarize_model`, `--speaker_embeddings`), word/char alignment (`--align_model`,
+  `--return_char_alignments`, `--interpolate_method`), and subtitle line control
+  (`--highlight_words`, `--max_line_width`, `--max_line_count`) — the layer that turns a
+  caption into styled, karaoke-timed, speaker-split social-video subtitles. See
+  [captions-transcription](captions-transcription.md).
+
+## Licensing
+Patterns/architecture only (adopt the idea, write our own code): Babylon.js (Apache-2.0),
+tldraw (custom), penpot (MPL), tsparticles (MIT), pixijs (MIT), pts (Apache-2.0),
+darktable (GPL, invoke binary at arm's length). editly (MIT), svgo (MIT), whisperX (BSD)
+are freely borrowable as ideas; we reimplement rather than vendor.

package/references/captions-transcription.md

@@ -58,4 +58,18 @@ The core CLI already does what we previously routed to whisperX or post-processi
 - `--task translate` (foreign audio -> English subs), `--clip_timestamps` (only given
   ranges).
 
+## When whisperX still wins (source-verified CLI surface)
+
+Core whisper covers word timestamps + highlight; reach for **whisperX** (BSD) when you
+need **speaker diarization** or tighter alignment. Its extra flags, read from source:
+`--diarize` (+ `--min_speakers`/`--max_speakers`, `--diarize_model`,
+`--speaker_embeddings`, `--hf_token`), forced alignment (`--align_model`, `--no_align`,
+`--return_char_alignments`, `--interpolate_method`), VAD tuning (`--vad_method`,
+`--vad_onset`/`--vad_offset`, `--chunk_size`), and subtitle line control
+(`--highlight_words`, `--max_line_width`, `--max_line_count`, `--segment_resolution`),
+plus `--suppress_numerals` and `--hotwords`. Use diarization + line-width control to turn
+a raw transcript into **speaker-split, karaoke-timed, safe-area-fit** social-video
+subtitles. For the agent-surface view of this (and editly/svgo), see
+[agent-native design surfaces](agent-native-design-surfaces.md).
+
 See `maggie-video` for the subcommands and the burn-in / soft-mux / compile options.

package/references/design-editor-patterns.md

@@ -72,6 +72,15 @@ pose/depth/segmentation) and IP-Adapter (reference image, style/composition tran
 The plugin-over-backend boundary (editor model stays; AI is a swappable backend)
 mirrors the arm's-length posture in [AI media generation](ai-media-generation.md).
 
+## Agent surfaces (MCP/skills/CLI these editors expose)
+
+For how these editors expose their *live document* to an agent — tldraw's `search`+`exec`
+canvas MCP, penpot's `execute_code` + `high_level_overview` bootstrap tools, darktable's
+params-as-data MCP with reusable style presets, Babylon.js WebMCP dual-adapter + writer
+arbitration, and the pixijs router-skill template — see
+[agent-native design surfaces](agent-native-design-surfaces.md). That reference is the
+"tools / MCP / skills / CLIs" dimension of the design reference library.
+
 ## Licensing
 
 Invoke binaries at arm's length (never vendor): inkscape, darktable (GPL). Concepts

package/references/image-recipes.md

@@ -57,6 +57,8 @@ pngquant --quality 60-82 --strip --output out.png in.png            # lossy PNG
 
 ```bash
 svgo --multipass -i in.svg -o out.svg      # keeps viewBox + title (responsive + a11y). If svgo absent, leave the SVG alone - never rasterize as a substitute.
+svgo --datauri base64 -p 2 -i icon.svg -o icon.txt  # embeddable data: URI (inline an icon); -p = coordinate precision
+# svgo is an ordered plugin pipeline (preset-default); `svgo --show-plugins` lists them, folder mode is `-f DIR -r --exclude PAT`
 resvg -w 512 in.svg out.png                # best-fidelity SVG -> PNG (or rsvg-convert -w 512); IM fallback (-background none -density 384) is lower fidelity
 ```
 

package/references/video-timeline-model.md

@@ -91,7 +91,14 @@ Compile the model to one `filter_complex`:
 - **output:** `-c:v libx264 -r fps -pix_fmt yuv420p -c:a aac out.mp4`.
 
 `mifi/editly` (MIT) and `Zulko/moviepy` (MIT) are working prior art that this JSON
-shape renders through ffmpeg without any GPL engine.
+shape renders through ffmpeg without any GPL engine. editly's `editSpec` (source-verified)
+is the closest match to adopt: `clips[] -> layers[] -> transitions` with a **fixed
+layer-type vocabulary** (`video, audio, image, image-overlay, title, subtitle, news-title,
+slide-in-text, fill-color, radial/linear-gradient, canvas, fabric, gl`), top-level
+`defaults.transition`, auto letterbox/fps-convert and auto audio crossfade/duck/normalize,
+and `canvas`/`fabric`/`gl` layers that take custom JS/shaders. An agent authors this spec
+directly; 1:1 / 9:16 / 16:9 presets fall out of `width/height`. See
+[agent-native design surfaces](agent-native-design-surfaces.md) for the CLI/spec surface.
 
 ### maggie_video.py compile
 
@@ -137,30 +144,69 @@ Concepts to grow the model (adopt the data shape / vocabulary; code only from th
 MIT/BSD sources - rlottie MIT, opentoonz/tahoma2d BSD; synfig/friction/wick/Natron
 GPL = concept only):
 
-- **Richer keyframe easing** (synfig). Extend `{t, v, ease}` with: **per-side ease**
-  (`easeIn` != `easeOut`), **`clamped`** (auto-smooth that won't overshoot the keyed
-  value), **`hold`/`constant`**, and optional **TCB** `{tension, continuity, bias}`.
-  Add **`fullRotations`** on a rotation keyframe (wick) to control spin count/direction
-  rather than shortest-path. These precompute to per-frame values for ffmpeg and map to
-  CSS/Lottie beziers. (compile currently interpolates linearly; this is the target
-  vocabulary.)
-- **Lottie JSON as the companion vector-motion-graphics format** (rlottie, MIT). For
-  logo stings, animated icons and kinetic type, use Lottie (After-Effects/Figma
-  exportable, in-browser renderable via lottie-web) alongside the MLT/NLE shape. Borrow
-  its primitives: **Trim-path** (`start%/end%/offset` - the formal version of the
-  "draw a line on" trick in [design-motion production](design-motion-production.md)),
-  **Repeater** (N copies with a transform + opacity ramp), **track mattes**
-  (`Alpha/Luma`), **transform parenting**, and **time remap** (`tm`).
-- **Nested clips / precomps** (wick/lottie). A clip may hold its own timeline with a
-  playback mode (`loop | playOnce | single`) and be instanced - reusable lower-thirds,
-  intro/outro stingers; a composable alternative to the flat track list.
-- **Decomposed transform + animatable pivot** (friction). Split transform into
-  `pos / scale / rot / shear / pivot / opacity`, each its own keyframe curve, with a
-  **movable pivot** for correct scale/rotate around a moving anchor.
-- **Blend-mode / compositing vocabulary** (Natron `MergingFunctionEnum`). The allowed
-  `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`).
+- **Richer keyframe easing** (synfig, source-verified `synfig-core/src/synfig/
+  interpolation.h` + `waypoint.h`). A waypoint carries **two independent interpolation
+  enums** — `before` and `after` (so easeIn != easeOut is just two enums, not a special
+  case). The real `enum Interpolation` (a plain enum, not enum class) is `TCB,
+  CONSTANT, LINEAR, HALT, MANUAL, UNDEFINED, NIL, CLAMPED` — note the ease-in/out curve
+  is **`HALT`** (there is no `INTERPOLATION_EASE`), `CLAMPED` is the no-overshoot
+  auto-smooth, `CONSTANT` is hold. **TCB** is `{tension, continuity, bias}` **plus a
+  4th `temporal_tension`** (tension on the time axis, separate from spatial). Two
+  data-shape borrows: every waypoint field has a paired **`*_flag` boolean** (explicit
+  "overridden vs inherited-default" tracking — the model for optional per-keyframe
+  overrides), and **`NIL`** is the "unset, inherit the default" sentinel (distinct from
+  `UNDEFINED`). Add **`fullRotations`** on a rotation keyframe (wick,
+  `Tween.js:48` — integer N = number of full turns, sign = direction) to express
+  "spin 3x clockwise" without angle unwrapping. These precompute to per-frame values for
+  ffmpeg and map to CSS/Lottie beziers. (compile currently interpolates linearly; this
+  is the target vocabulary.)
+- **Lottie JSON as the companion vector-motion-graphics format** (rlottie, **MIT -
+  citable for code**; names verified in `src/lottie/lottiemodel.h`, which uses `model::`
+  classes, **not** the older `LOT*Data` names). For logo stings, animated icons and
+  kinetic type, use Lottie (After-Effects/Figma exportable, in-browser renderable via
+  lottie-web) alongside the MLT/NLE shape. The single most useful data-shape is the
+  uniform **`Property<T>`** wrapper with **`isStatic()`** - every animatable value is
+  either a constant or a keyframed track, queried the same way (adopt this as the base
+  of the JSON model). Borrow its primitives: **`Trim`** (`mStart/mEnd/mOffset` %, +
+  `TrimType{Simultaneously, Individually}` - the formal version of the "draw a line on"
+  trick in [design-motion production](design-motion-production.md)), **`Repeater`**
+  (`mCopies/mOffset` + a `Transform` with `mStartOpacity -> mEndOpacity` ramp across
+  copies, capped at 10000), **track mattes** `MatteType{None, Alpha, AlphaInv, Luma,
+  LumaInv}` (note the **inverted** variants), **`Mask`** (a *distinct* mechanism from
+  mattes: `Mode{None, Add, Subtract, Intersect, Difference}` + an invert flag),
+  **transform parenting**, **time remap** (`mTimeRemap`, "tm"), and the generative
+  primitives **`Polystar`** (`PolyType{Star, Polygon}`, one shape for both via inner/
+  outer radius+roundness), separate `GradientFill`/`GradientStroke`, and stroke `Dash`.
+- **Nested clips / precomps** (wick/lottie, verified `engine/src/base/Clip.js`). A
+  `Clip` owns its own `Wick.Timeline` (nestable sub-timelines) with an **`animationType`**
+  (the real field; values `'loop' | 'single' | 'playOnce'` from
+  `Wick.Clip.animationTypes` - *not* `playbackMode`, and ignore a stale "oneFrame" code
+  comment) and is instanced via a tracked `_clones` list - reusable lower-thirds,
+  intro/outro stingers; a composable alternative to the flat track list. Wick's tween
+  model is also worth copying: keys are **sparse** and interpolation is a static function
+  over two keys (`Tween.interpolate(a, b, playhead)`, `easingType` in
+  `none|in|out|in-out`), not baked per frame.
+- **Decomposed transform + animatable pivot** (friction, verified
+  `src/core/Animators/transformanimator.h` - a 3-level hierarchy
+  `BasicTransformAnimator -> AdvancedTransformAnimator -> BoxTransformAnimator`). Split
+  transform into `pos / scale / rot / shear / pivot / opacity`, each its own keyframe
+  curve (`QPointFAnimator`/`QrealAnimator`), with the **pivot itself an animated point**
+  kept separate from **shear** (most Lottie-style models have neither an animatable pivot
+  nor shear), and `setPivotFixedTransform` to move the pivot without disturbing the box.
+  Parenting is a first-class edge (`setParentTransformAnimator` + stored `mPostTransform`
+  matrix); grouped "is-animated" queries over a property subset back a JSON `animated:
+  bool` rollup.
+- **Blend-mode / compositing vocabulary** (Natron `MergingFunctionEnum`, verified
+  `Global/Enums.h` - 39 members, `eMergeATop = 0`). The allowed `blendMode` values on
+  overlay clips: Porter-Duff (`Over, Under, In, Out, ATop, Copy, Matte`) + the standard
+  blends (`Multiply, Screen, Overlay, SoftLight, HardLight, ColorBurn, ColorDodge,
+  Difference, Exclusion, Hue, Saturation, Color, Luminosity`) + a fuller set worth
+  adopting: `ConjointOver, DisjointOver, PinLight, Average, Divide, Plus, Minus, From,
+  Freeze, Reflect, GrainExtract, GrainMerge, Geometric, Hypot, Mask, Stencil, Max, Min,
+  XOR`. Natron models blend as a **per-node knob** on a Merge node with named inputs
+  (A/B + optional mask), not a flat per-layer z-order field - so for branched effects
+  treat blend as a property on a merge/group node (see the effect-graph escape hatch
+  below).
 - **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
@@ -175,6 +221,12 @@ GPL = concept only):
   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.
+- **Shared / linked parameters** (synfig exported ValueNodes, `canvas.h`
+  `add_value_node(node, id)`). A canvas holds **named (exported) value nodes**, and many
+  parameters reference the same node by id - one source of truth for a color, duration or
+  curve reused across clips. Borrow as a timeline-level **`defs` map keyed by id** with
+  properties referencing `{$ref: id}` (a brand accent or a shared ease authored once,
+  linked everywhere).
 - **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**