@pinepaper.studio/mcp-server 1.6.15 → 1.6.17

package/README.de.md

@@ -19,7 +19,7 @@
 
 Der PinePaper MCP-Server lässt KI-Assistenten über das Model Context Protocol Grafiken in [PinePaper Studio](https://pinepaper.studio) erstellen und animieren. Funktioniert mit jeder KI, die MCP-Tool-Aufrufe unterstützt (Claude, GPT, Gemini, lokale Modelle usw.).
 
-Der Server bietet **154 Tools**: Zeichnen, Animation, Diagramme, Karten, Typografie, Physik, Bildbearbeitung, Datenvisualisierung und Export:
+Der Server bietet **159 Tools**: Zeichnen, Animation, Diagramme, Karten, Typografie, Physik, Bildbearbeitung, Datenvisualisierung und Export:
 
 - Text, Formen, Geometrie und komplexe Grafiken erstellen
 - Mit deklarativen **Relationen** animieren statt mit Keyframes

package/README.es.md

@@ -19,7 +19,7 @@
 
 El servidor MCP de PinePaper permite a los asistentes de IA crear y animar gráficos en [PinePaper Studio](https://pinepaper.studio) a través del Model Context Protocol. Funciona con cualquier IA que soporte llamadas a herramientas MCP (Claude, GPT, Gemini, modelos locales, etc.).
 
-Expone **154 herramientas**: dibujo, animación, diagramas, mapas, tipografía, física, edición de imágenes, visualización de datos y exportación:
+Expone **159 herramientas**: dibujo, animación, diagramas, mapas, tipografía, física, edición de imágenes, visualización de datos y exportación:
 
 - Crear texto, formas, geometría y gráficos complejos
 - Animar con **relaciones** declarativas en lugar de fotogramas clave

package/README.fr.md

@@ -19,7 +19,7 @@
 
 Le serveur MCP PinePaper permet aux assistants IA de créer et d'animer des graphiques dans [PinePaper Studio](https://pinepaper.studio) via le Model Context Protocol. Compatible avec toute IA gérant les appels d'outils MCP (Claude, GPT, Gemini, modèles locaux, etc.).
 
-Il expose **154 outils** : dessin, animation, diagrammes, cartes, typographie, physique, retouche d'image, visualisation de données et export :
+Il expose **159 outils** : dessin, animation, diagrammes, cartes, typographie, physique, retouche d'image, visualisation de données et export :
 
 - Créer du texte, des formes, de la géométrie et des graphiques complexes
 - Animer avec des **relations** déclaratives plutôt que des images clés

package/README.hi.md

@@ -19,7 +19,7 @@
 
 PinePaper MCP सर्वर AI असिस्टेंट्स को Model Context Protocol के ज़रिए [PinePaper Studio](https://pinepaper.studio) में ग्राफ़िक्स बनाने और एनिमेट करने देता है। MCP टूल कॉलिंग वाले किसी भी AI (Claude, GPT, Gemini, लोकल मॉडल आदि) के साथ काम करता है।
 
-सर्वर **154 टूल** देता है — ड्रॉइंग, एनिमेशन, डायग्राम, नक्शे, टाइपोग्राफ़ी, फिज़िक्स, इमेज एडिटिंग, डेटा विज़ुअलाइज़ेशन और एक्सपोर्ट:
+सर्वर **159 टूल** देता है — ड्रॉइंग, एनिमेशन, डायग्राम, नक्शे, टाइपोग्राफ़ी, फिज़िक्स, इमेज एडिटिंग, डेटा विज़ुअलाइज़ेशन और एक्सपोर्ट:
 
 - टेक्स्ट, आकृतियाँ, ज्यामिति और जटिल ग्राफ़िक्स बनाना
 - कीफ़्रेम की जगह व्यवहार बताने वाले **रिलेशन** से एनिमेशन

package/README.ja.md

@@ -19,7 +19,7 @@
 
 PinePaper MCP サーバーは、MCP 経由で AI アシスタントが [PinePaper Studio](https://pinepaper.studio) 上にグラフィックを作成・アニメーションさせるためのサーバーです。MCP ツールコールに対応した AI（Claude、GPT、Gemini、ローカルモデルなど）で動作します。
 
-**154 個のツール**を提供 — 描画・アニメーション・図・地図・タイポグラフィ・物理・画像編集・データ可視化・エクスポート：
+**159 個のツール**を提供 — 描画・アニメーション・図・地図・タイポグラフィ・物理・画像編集・データ可視化・エクスポート：
 
 - テキスト、図形、ジオメトリ、複雑なグラフィックの作成
 - キーフレームではなく、ふるまいを宣言する**リレーション**でアニメーション

package/README.ko.md

@@ -19,7 +19,7 @@
 
 PinePaper MCP 서버는 AI 어시스턴트가 MCP를 통해 [PinePaper Studio](https://pinepaper.studio)에서 그래픽을 만들고 애니메이션하게 해줍니다. MCP 툴 콜을 지원하는 모든 AI(Claude, GPT, Gemini, 로컬 모델 등)와 호환됩니다.
 
-**154개의 툴** 제공 — 드로잉, 애니메이션, 다이어그램, 지도, 타이포그래피, 물리, 이미지 편집, 데이터 시각화, 내보내기:
+**159개의 툴** 제공 — 드로잉, 애니메이션, 다이어그램, 지도, 타이포그래피, 물리, 이미지 편집, 데이터 시각화, 내보내기:
 
 - 텍스트·도형·기하·복잡한 그래픽 생성
 - 키프레임 대신 행동을 선언하는 **릴레이션**으로 애니메이션

package/README.md

@@ -30,7 +30,7 @@
 
 PinePaper MCP Server enables AI assistants to create and animate graphics in [PinePaper Studio](https://pinepaper.studio) via the Model Context Protocol (MCP). Works with any AI that supports MCP tool calling (Claude, GPT, Gemini, local models, etc.).
 
-The server exposes **154 tools** across drawing, animation, diagrams, maps, typography, physics, image editing, data visualization, and export. Using natural language, you can:
+The server exposes **159 tools** across drawing, animation, diagrams, maps, typography, physics, image editing, data visualization, and export. Using natural language, you can:
 
 - Create geometric shapes, text collages, diagrams, and data charts
 - Apply 37+ character-level text effects and 28+ vertex deformation presets
@@ -41,7 +41,7 @@ The server exposes **154 tools** across drawing, animation, diagrams, maps, typo
 
 ## Running it: local or hosted
 
-**Local is free and complete.** Every one of the 154 tools works when you run
+**Local is free and complete.** Every one of the 159 tools works when you run
 this server yourself. There is no reduced tier and nothing held back.
 
 What it needs:
@@ -246,6 +246,105 @@ If you do not want an agent executing anything, `code` mode is a first-class pat
 - Puppeteer mode launches Chrome with `--no-sandbox` and `--disable-setuid-sandbox`. That is routine for headless automation and it does weaken Chrome's own process sandbox. If that matters where you are running it, use `code` mode or put the server in a container.
 - Puppeteer itself is an **optional** peer dependency, kept out of the default tree precisely because a headless browser plus an install script is what scanners flag hardest. Install it only if you want the executing mode.
 
+## What's new in 1.6.17
+
+### New: tell an agent "at 4 s, make it orange"
+
+`pinepaper_modify_item` takes `atTime`: the change is written as a keyframe at
+that moment, the same as dragging with auto-key on, eased from the previous
+value and without disturbing the rest of the animation.
+`pinepaper_query_mutations` shows a property's values over time.
+
+### New: cuts on the beat
+
+`pinepaper_beat_cuts` analyses a music track, fits a beat grid and returns cut
+points on every beat, every bar or every N beats — and can split a clip at each.
+When the tempo is uncertain it says so and lists the likely alternatives;
+`bpm` or `bpmHint` settles it.
+
+### New: exact frame counts, and larger canvases
+
+- `pinepaper_agent_export` takes `frames` for an exact frame count (a duration
+  rounds up), for segments that must line up.
+- Canvases up to 16384 px per side, for digital out-of-home and projection;
+  above 8192 the result notes that Safari and iOS may not manage it.
+- `pinepaper_import_image` takes `maxEdge` (or `'native'`) and `nativeSize`, and
+  says when the studio stored an image smaller than its source.
+- `pinepaper_media` `upload_video` takes `fit` (`contain`, `cover`, `none`), and
+  `scale` is documented as relative to it.
+
+### Changed: exports say more about what they produced
+
+- When an MP4 cannot be made at the requested size, the file is named by what it
+  is (WebM) and a warning says why.
+- A video whose animation did not play, or whose encoder froze, is flagged.
+- Asking for ProRes or HAP explains the route that works (a PNG sequence).
+- Frame captures, region stills and flash checks wait for video on screen, and
+  report whether they could.
+- The engine's structured warnings reach the caller whole.
+
+### Fixed
+
+- `pinepaper_accessibility_check` judged text only at the current playhead, so
+  timed captions could pass unchecked; it now samples the timeline, and says
+  when no text was visible rather than passing.
+- `pinepaper_agent_export` accepts `fps` and `scale` for APNG.
+
+## What's new in 1.6.16
+
+### New: video editing on the timeline
+
+`pinepaper_media` gains `split` (cut a clip in two at a time),
+`add_transition` (a crossfade or a dip between two clips that meet), and
+`set_clip` with `timeOffset` to move a clip, not only trim it. Uploads take
+`atPlayhead: true` to start at the current playback time. A studio that cannot
+do one of these says so rather than reporting success.
+
+### New: AI image generation (beta)
+
+`pinepaper_generate` creates images with AI models in the PinePaper cloud and
+can place the first one on the canvas; `pinepaper_generate_estimate` prices a
+request and lists the models, free. It is charged per image, needs a service
+account key (`PINEPAPER_API_KEY`), and is enabled per organisation during the
+beta — without it the tools say so, and nothing is charged.
+
+Words are never drawn by the model: pass them as `input.text` (headline,
+subhead, caption, call to action, label) and they are added as real, editable
+PinePaper text over the image, laid out inside the title-safe area and given a
+dark backing only where the image behind them is too bright to read.
+
+### New: add to an animation instead of replacing it
+
+`pinepaper_keyframe_animate` takes `append: true` to add keys to an item's
+existing animation — a button press after an entrance. Without it, a second
+call replaces the animation, and the result now says when that happened.
+
+### New: byte-identical exports
+
+`pinepaper_agent_export` takes `deterministic: true` for MP4 and WebM: the same
+scene gives the same file, so exports can be checksummed or cached by hash. If
+a run could not be pinned, the result says not to rely on the hash.
+
+### Fixed
+
+- `pinepaper_import_asset` with a `url` failed on every call after fetching the
+  file successfully.
+- `pinepaper_sound` `render_soundtrack` timed out on longer soundtracks; it now
+  has the same time budget as other exports.
+- `pinepaper_audio_beats` answered success with no result for larger audio, and
+  could not read a local file path. Both work now.
+- `pinepaper_camera_animate` without keyframes failed with a raw JSON error; it
+  now says what `keyframes` needs.
+- `pinepaper_precomp`: `create` returned an internal id that no tool accepted,
+  and `add` / `remove` could not work at all. All three now round-trip the
+  precomp's item id, and a failed `remove` is reported.
+- `pinepaper_media` `set_time_remap`, `speed_ramp`, `match_cut` and the track
+  matte actions accept the media id that upload returns, as documented.
+- `modify_item` `content` on text whose content is keyframed now warns that the
+  keyframes override it.
+- Exporting a landscape canvas for a portrait platform (TikTok, Stories) — or
+  the reverse — is a fidelity warning with the fix, not only a note.
+
 ## What's new in 1.6.15
 
 ### New: the PinePaper mark
@@ -1171,7 +1270,7 @@ Fourteen new tools (121 → 135) and new actions across the surface — the rele
 
 ## Toolkits & Token Budget
 
-154 tools is a lot of context. The server ships a **toolkit** system that serves only the tools a given client needs, plus a **verbosity** system that controls how long each tool description is.
+159 tools is a lot of context. The server ships a **toolkit** system that serves only the tools a given client needs, plus a **verbosity** system that controls how long each tool description is.
 
 **Toolkit profiles** (`PINEPAPER_TOOLKIT`):
 
@@ -1376,7 +1475,7 @@ Generate instruction/code pairs for LLM fine-tuning:
 
 ## Tools Reference
 
-All 154 tools, grouped by the tag used for toolkit filtering.
+All 159 tools, grouped by the tag used for toolkit filtering.
 
 ### Canvas (`canvas`)
 | Tool | Description |
@@ -1477,6 +1576,9 @@ All 154 tools, grouped by the tag used for toolkit filtering.
 |------|-------------|
 | `pinepaper_execute_generator` | Run a background generator |
 | `pinepaper_list_generators` | List available generators |
+| `pinepaper_generate` | AI image generation in the PinePaper cloud (charged; beta, per organisation) |
+| `pinepaper_generate_estimate` | Free price check, and the model list |
+| `pinepaper_generate_status` | Collect a generation that outlived its timeout |
 | `pinepaper_apply_effect` | Apply sparkle, blast, and other effects |
 | `pinepaper_text_effect` | 37 character-level text animations; replaces the text with one keyframed item per character |
 | `pinepaper_add_filter` | Add an image filter |
@@ -1595,6 +1697,8 @@ All 154 tools, grouped by the tag used for toolkit filtering.
 | `pinepaper_analyze_design` | Analyze design quality |
 | `pinepaper_validate_design` | Validate against design rules |
 | `pinepaper_validate` | General validation |
+| `pinepaper_beat_cuts` | Cut points on the music's beats or bars; split a clip at each |
+| `pinepaper_query_mutations` | A property's keyframe series over time |
 | `pinepaper_accessibility_check` | Text contrast and flashing (WCAG), as a heuristic screen |
 | `pinepaper_validate_scene` | Validate scene integrity |
 | `pinepaper_instantiate_ontology` | Compile a pp: design graph into a scene |
@@ -1871,6 +1975,8 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
 |----------|-------------|---------|
 | `PINEPAPER_STUDIO_URL` | PinePaper Studio URL to connect to (`/editor` is appended automatically) | `https://pinepaper.studio` |
 | `PINEPAPER_HEADLESS` | Run the browser headless (set `false` to watch it work) | `true` |
+| `PINEPAPER_API_KEY` | Service-account key (`pp_sa_…`) for the cloud-backed tools (`pinepaper_generate`) | — |
+| `PINEPAPER_CLOUD_URL` | The PinePaper cloud those tools call | `https://cloud.pinepaper.studio` |
 | `PINEPAPER_EXECUTION_MODE` | `puppeteer` (execute in a real browser) or `code` (return generated code only) | `puppeteer` |
 | `PINEPAPER_EXPORT_DIR` | Directory for exported files | `<tmpdir>/pinepaper-exports` |
 | `PINEPAPER_LOCALE` | Language locale code | `en` |

package/README.pt-BR.md

@@ -19,7 +19,7 @@
 
 O servidor MCP do PinePaper permite que assistentes de IA criem e animem gráficos no [PinePaper Studio](https://pinepaper.studio) via Model Context Protocol. Funciona com qualquer IA que suporte chamadas de ferramenta MCP (Claude, GPT, Gemini, modelos locais etc.).
 
-São **154 ferramentas**: desenho, animação, diagramas, mapas, tipografia, física, edição de imagens, visualização de dados e exportação:
+São **159 ferramentas**: desenho, animação, diagramas, mapas, tipografia, física, edição de imagens, visualização de dados e exportação:
 
 - Criar texto, formas, geometria e gráficos complexos
 - Animar com **relações** declarativas em vez de keyframes

package/README.zh-CN.md

@@ -19,7 +19,7 @@
 
 PinePaper MCP 服务器让 AI 助手通过 MCP 协议在 [PinePaper Studio](https://pinepaper.studio) 中创建和驱动图形动画。兼容任何支持 MCP 工具调用的 AI（Claude、GPT、Gemini、本地模型等）。
 
-服务器提供 **154 个工具**，覆盖绘图、动画、图表、地图、排版、物理、图像编辑、数据可视化与导出：
+服务器提供 **159 个工具**，覆盖绘图、动画、图表、地图、排版、物理、图像编辑、数据可视化与导出：
 
 - 创建文本、形状、几何图形与复杂图稿
 - 用行为驱动的**关系（relations）**做动画，而不是逐帧关键帧

package/dist/build-info.json

@@ -1,5 +1,5 @@
 {
-  "sha": "21f9ebb",
+  "sha": "b387e3e",
   "dirty": false,
-  "builtAt": "2026-09-25T20:36:58.520Z"
+  "builtAt": "2026-09-27T07:36:09.211Z"
 }

package/dist/ontology/upstream-vocabulary.d.ts

@@ -4,9 +4,9 @@
  * FxTool's ITEM_TYPE_MAP and type classes (anchor, description, parentType,
  * mcpTool, mcpAction), read from the loaded module.
  *
- * Source: FxTool origin/main 253a01a04c886713f610e619ac6205e59751dbb4
+ * Source: FxTool origin/main 9dd578afaa83c6286bfa2f554e8665407be400e1
  *   js/ontology/Vocabulary.js
- * sha256: 8c39f8ad6d2da359
+ * sha256: 48fb80f82d3d3220
  *
  * vocabulary.ts merges these over its hand-written port: the engine's map
  * wins where the two disagree, and a class the port lacks is added.

package/dist/ontology/upstream-vocabulary.js

@@ -4,9 +4,9 @@
  * FxTool's ITEM_TYPE_MAP and type classes (anchor, description, parentType,
  * mcpTool, mcpAction), read from the loaded module.
  *
- * Source: FxTool origin/main 253a01a04c886713f610e619ac6205e59751dbb4
+ * Source: FxTool origin/main 9dd578afaa83c6286bfa2f554e8665407be400e1
  *   js/ontology/Vocabulary.js
- * sha256: 8c39f8ad6d2da359
+ * sha256: 48fb80f82d3d3220
  *
  * vocabulary.ts merges these over its hand-written port: the engine's map
  * wins where the two disagree, and a class the port lacks is added.

package/dist/tools/definitions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"definitions.d.ts","sourceRoot":"","sources":["../../src/tools/definitions.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,oCAAoC,CAAC;AAC1D,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AA+B/C,eAAO,MAAM,cAAc,6kbAyK+G,CAAC;AAW3I,eAAO,MAAM,eAAe,EAAE,IAAI,EAukRjC,CAAC;AAEF;;GAEG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAE5D;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,MAAM,EAAE,CAEvC;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,EAAE,CAO3D;AAED;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;AAE9D;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,aAAa,GAAG,IAAI,EAAE,CAQrE"}
+{"version":3,"file":"definitions.d.ts","sourceRoot":"","sources":["../../src/tools/definitions.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,oCAAoC,CAAC;AAC1D,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AA+B/C,eAAO,MAAM,cAAc,6kbAyK+G,CAAC;AAW3I,eAAO,MAAM,eAAe,EAAE,IAAI,EA6tRjC,CAAC;AAEF;;GAEG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAE5D;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,MAAM,EAAE,CAEvC;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,EAAE,CAO3D;AAED;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;AAE9D;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,aAAa,GAAG,IAAI,EAAE,CAQrE"}

package/dist/tools/definitions.js

@@ -261,12 +261,12 @@ COMMON PRESETS:
 - hd-landscape: 1920x1080
 - hd-portrait: 1080x1920
 
-Max canvas size: 8192x8192 (a 5400x1350 carousel panorama fits). For wedding invitations, event cards, or detailed designs, use at least 1080x1080 or larger.`,
+Max canvas size: 16384 per side (a 12000 px DOOH or projection canvas fits); above 8192 Safari / iOS may not render it, Chrome and Firefox do. For wedding invitations, event cards, or detailed designs, use at least 1080x1080 or larger.`,
         inputSchema: {
             type: 'object',
             properties: {
-                width: { type: 'number', description: 'Canvas width in pixels (100-8192)' },
-                height: { type: 'number', description: 'Canvas height in pixels (100-8192)' },
+                width: { type: 'number', description: 'Canvas width in pixels (100-16384)' },
+                height: { type: 'number', description: 'Canvas height in pixels (100-16384)' },
                 preset: {
                     type: 'string',
                     description: 'Optional preset name',
@@ -732,6 +732,8 @@ Use the collage group's id for palette/collageStyle; use a child letter's id for
                         isDecorative: { type: 'boolean', description: 'Mark as decorative/non-interactive' },
                     },
                 },
+                atTime: { type: 'number', minimum: 0, description: 'AUTO-KEY: instead of a static edit, write these properties as keyframes at this time (seconds) — the same as a user dragging with auto-key on. Eased from the previous value; other keys and other properties\' curves are kept. "At 4 s make it orange" is { properties: { fillColor: "orange" }, atTime: 4 }.' },
+                easing: { type: 'string', description: 'atTime: easing of the segment arriving at the new key (default linear).' },
             },
             required: ['itemId', 'properties'],
         },
@@ -1152,6 +1154,8 @@ EXAMPLES:
                     type: 'number',
                     description: 'Maximum height constraint in pixels',
                 },
+                maxEdge: { anyOf: [{ type: 'integer', minimum: 1 }, { type: 'string', enum: ['native'] }], description: "The longest edge the studio STORES the image at (px); 'native' keeps every pixel. Default: the studio's cap, which follows the canvas on desktop. The result says when the image was stored smaller than its source." },
+                nativeSize: { type: 'boolean', description: 'Place the image at its source footprint even if it was stored smaller.' },
                 mask: {
                     type: 'string',
                     enum: ['circle', 'rounded', 'hexagon', 'star'],
@@ -1729,6 +1733,47 @@ EXAMPLES:
             required: ['action'],
         },
     },
+    {
+        name: 'pinepaper_beat_cuts',
+        annotations: { title: 'Beat-Snapped Cuts', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+        description: `Cut on the music: analyse a track's beats (or take beat times you already have), fit a beat grid, and return cut points on every beat, every bar, or every N beats — optionally splitting a video or audio clip at each one.
+
+- source: the music — an upload id, URL, data: URL or local file path. Or beats: [seconds] to skip the analysis.
+- every: 'beat' (default) | 'bar' | N beats. beatsPerBar (default 4). range: [from, to] seconds.
+- bpm: the tempo, if you know it (the grid's phase is still fitted to the music). Otherwise the studio's detection and its usual confusions (double, half, 3:4, 4:3 …) are scored against the music and the best is used; bpmHint: [min, max] keeps the choice in a range. The result lists the candidates, and says lowConfidence with a warning when the tempo is uncertain — pass bpm then.
+- clipId: split this clip at each cut, in order; cuts outside the clip are skipped and listed.
+
+Returns cuts (seconds), the grid (bpm, phase, period, confidence) and, with clipId, the pieces' ids.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                source: { type: 'string' },
+                beats: { type: 'array', items: { type: 'number' } },
+                bpm: { type: 'number' },
+                bpmHint: { type: 'array', items: { type: 'number' }, minItems: 2, maxItems: 2, description: '[min, max] bpm to choose within.' },
+                includeOnsets: { type: 'boolean', description: 'Also return the detected onsets (for diagnosing a tempo pick).' },
+                every: { anyOf: [{ type: 'string', enum: ['beat', 'bar'] }, { type: 'integer', minimum: 1, maximum: 64 }] },
+                beatsPerBar: { type: 'integer', minimum: 1, maximum: 16 },
+                range: { type: 'array', items: { type: 'number' }, minItems: 2, maxItems: 2 },
+                clipId: { type: 'string' },
+            },
+        },
+    },
+    {
+        name: 'pinepaper_query_mutations',
+        annotations: { title: 'Query Property Keyframes', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+        description: `A property's values over time: the item's keyframe series ({t, frame, value, easing} per key), for one property or all, optionally within [from, to] seconds. The read side of modify_item { atTime } (auto-key): "what changed at 4 s?", "show the colour over time". It reads the item's keyframe track; it does not yet say WHO made each change or the value before it — that needs the studio's mutation log.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                itemId: { type: 'string' },
+                property: { type: 'string', description: 'One property; all animated properties when omitted.' },
+                range: { type: 'array', items: { type: 'number' }, minItems: 2, maxItems: 2, description: '[from, to] seconds.' },
+                fps: { type: 'number', description: 'For the frame numbers (default 30).' },
+            },
+            required: ['itemId'],
+        },
+    },
     {
         name: 'pinepaper_accessibility_check',
         annotations: {
@@ -1750,11 +1795,96 @@ EXAMPLE: { checks: ["contrast", "flash"], duration: 6, fps: 20 }`,
             type: 'object',
             properties: {
                 checks: { type: 'array', items: { type: 'string', enum: ['contrast', 'flash'] }, description: 'Which checks (default both).' },
-                duration: { type: 'number', exclusiveMinimum: 0, maximum: 120, description: 'flash: seconds of the timeline to sample (default 5).' },
+                duration: { type: 'number', exclusiveMinimum: 0, maximum: 120, description: 'Seconds of the timeline to sample (default 5): flash samples it at fps; contrast at 0 s, inside each text lifetime, at keyframe times and every second.' },
                 fps: { type: 'integer', minimum: 10, maximum: 60, description: 'flash: samples per second (default 20).' },
             },
         },
     },
+    {
+        name: 'pinepaper_generate',
+        annotations: { title: 'Generate Image (cloud)', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+        description: `Generate images with an AI model in the PinePaper cloud, and optionally place the first one on the canvas. CHARGED per output — price it first with pinepaper_generate_estimate (free).
+
+Needs a service-account key in PINEPAPER_API_KEY (pp_sa_…, render:create scope). It is an internal beta enabled per organisation: without it the result says "not enabled for your organisation", and nothing is charged. Every refusal says whether anything was charged.
+
+- model or useCase: a model id from pinepaper_generate_estimate {listModels: true}, or a use case and the cloud picks its default (hero stills, plates, text in the image, character-consistent edits).
+- input: { prompt, aspect ('16:9' | '9:16' | '1:1' | '4:5'), n (1-4), seed?, negativePrompt?, imageUrls? (https references for edit models) }.
+- brief / designRef: always passed on; the cloud records each generation against the design.
+- place: 'cover' (fill the canvas, centred; default when true) or 'contain' — places the first asset: an image as an image item, a video as a video layer (with its durationSeconds). The fit uses the asset's delivered size, not the requested aspect.
+- timeoutSec: how long to wait (default 180). A job that outlives it keeps running and is only charged if it delivers; collect it with pinepaper_generate_status.
+
+WORDS ARE VECTOR: give words as input.text [{content, role?: headline|subhead|caption|cta|label, font?}]. The model makes a text-free plate; the words come back as textLayers (plus a hint), and with place they are added as real, editable text over it: headline top-left (Anton by default), subhead below, caption / cta bottom-left, label top-right, inside title-safe, each contrast-checked against the plate (a dark scrim is added only where it falls short of WCAG 4.5:1, or 3:1 for large text). Their item ids are in placement.text.
+
+The result: assets [{assetId, ref, width, height}] — the sizes the files HAVE (a model may pick its own size for an aspect), chargedUsd, and any model notes (e.g. a SynthID watermark) to pass on.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                model: { type: 'string' },
+                useCase: { type: 'string' },
+                input: {
+                    type: 'object',
+                    properties: {
+                        prompt: { type: 'string' },
+                        aspect: { type: 'string', enum: ['16:9', '9:16', '1:1', '4:5'] },
+                        n: { type: 'integer', minimum: 1, maximum: 4 },
+                        seed: { type: 'integer' },
+                        negativePrompt: { type: 'string' },
+                        imageUrls: { type: 'array', items: { type: 'string' }, maxItems: 14, description: 'Reference / start-frame images: https URLs, or your own generated images as their ref "/scene-assets/<id>" (chain a still into a video or a character edit).' },
+                        seconds: { type: 'number', exclusiveMinimum: 0, maximum: 60, description: 'Video models: clip length; each model allows its own lengths (listModels).' },
+                        text: { type: 'array', maxItems: 12, items: { type: 'object', properties: { content: { type: 'string' }, role: { type: 'string', enum: ['headline', 'subhead', 'caption', 'cta', 'label'] }, font: { type: 'string' } }, required: ['content'] }, description: 'Words for the design. The model never draws them: the plate comes back text-free and these return as textLayers — with place, laid out as real PinePaper text.' },
+                        allowText: { type: 'boolean', description: 'Let the MODEL draw text — eval-tier models only (e.g. ideogram-v3); refused (422) elsewhere. Prefer text.' },
+                    },
+                    required: ['prompt'],
+                },
+                brief: { type: 'string' },
+                designRef: { type: 'object', properties: { kind: { type: 'string' }, id: { type: 'string' } }, required: ['kind', 'id'] },
+                place: { anyOf: [{ type: 'boolean' }, { type: 'string', enum: ['cover', 'contain'] }] },
+                timeoutSec: { type: 'integer', minimum: 10, maximum: 1800 },
+            },
+            required: ['input'],
+        },
+    },
+    {
+        name: 'pinepaper_generate_estimate',
+        annotations: { title: 'Estimate Generation (free)', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+        description: `Free: price a pinepaper_generate call before making it, or list the models. { listModels: true } returns every model you may use with its price per output, use cases, licence notes and the defaults per use case; { model | useCase, input } returns the estimate for that request. Needs PINEPAPER_API_KEY, like pinepaper_generate.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                model: { type: 'string' },
+                useCase: { type: 'string' },
+                input: {
+                    type: 'object',
+                    properties: {
+                        prompt: { type: 'string' },
+                        aspect: { type: 'string', enum: ['16:9', '9:16', '1:1', '4:5'] },
+                        n: { type: 'integer', minimum: 1, maximum: 4 },
+                        seed: { type: 'integer' },
+                        negativePrompt: { type: 'string' },
+                        imageUrls: { type: 'array', items: { type: 'string' }, maxItems: 14, description: 'Reference / start-frame images: https URLs, or your own generated images as their ref "/scene-assets/<id>" (chain a still into a video or a character edit).' },
+                        seconds: { type: 'number', exclusiveMinimum: 0, maximum: 60, description: 'Video models: clip length; each model allows its own lengths (listModels).' },
+                        text: { type: 'array', maxItems: 12, items: { type: 'object', properties: { content: { type: 'string' }, role: { type: 'string', enum: ['headline', 'subhead', 'caption', 'cta', 'label'] }, font: { type: 'string' } }, required: ['content'] }, description: 'Words for the design. The model never draws them: the plate comes back text-free and these return as textLayers — with place, laid out as real PinePaper text.' },
+                        allowText: { type: 'boolean', description: 'Let the MODEL draw text — eval-tier models only (e.g. ideogram-v3); refused (422) elsewhere. Prefer text.' },
+                    },
+                    required: ['prompt'],
+                },
+                listModels: { type: 'boolean' },
+            },
+        },
+    },
+    {
+        name: 'pinepaper_generate_status',
+        annotations: { title: 'Generation Status', readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+        description: `Collect a pinepaper_generate job that outlived its timeoutSec: its status, and when done its assets and chargedUsd. place: 'cover' | 'contain' places the first image, as pinepaper_generate does.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                jobId: { type: 'string' },
+                place: { anyOf: [{ type: 'boolean' }, { type: 'string', enum: ['cover', 'contain'] }] },
+            },
+            required: ['jobId'],
+        },
+    },
     {
         name: 'pinepaper_render_batch',
         annotations: {
@@ -2043,15 +2173,18 @@ EXAMPLE: { times: [0, 0.5, 1, 1.5, 2], seed: 42 }`,
         description: `Bring VIDEO and AUDIO onto the canvas from a URL, and control playback. Uploaded video is a first-class canvas item (drag, scale, animate, export like any shape); audio rides the timeline.
 
 ACTIONS:
-- upload_video: { url (required), position?, scale?, timeOffset? (timeline start, s), clipInPoint?, clipOutPoint? (trim, s) } → { id, duration, width, height, name }
-- upload_audio: { url (required), volume? (0–1, default 1), loop?, muted?, timeOffset? } → { id, registryId, duration, name }. Pass loop EXPLICITLY — loop:true for a music bed, loop:false for a voice-over or sting; when omitted, the studio's own default applies and differs between builds.
+- upload_video: { url (required), position?, fit? ('contain' default | 'cover' | 'none' = source pixels), scale? (a multiplier on that fit — with fit 'none', on the source pixels), timeOffset? (timeline start, s) or atPlayhead?: true (start at the current playback time), clipInPoint?, clipOutPoint? (trim, s) } → { id, duration, width, height, name }
+- upload_audio: { url (required), volume? (0–1, default 1), loop?, muted?, timeOffset? or atPlayhead? } → { id, registryId, duration, name }. Pass loop EXPLICITLY — loop:true for a music bed, loop:false for a voice-over or sting; when omitted, the studio's own default applies and differs between builds.
 - list: → all media [{ id, kind, duration, … }]
 - remove: { id } → removed boolean
 - set_playback_rate: { id, rate (0.25–4) } → applies to video or audio
-- set_clip: { id, inPoint, outPoint (media-time s, outPoint > inPoint) } → re-trim an ALREADY-uploaded clip (video or audio)
+- set_clip: { id, inPoint, outPoint (media-time s, outPoint > inPoint), timeOffset? (canvas s: also MOVE the clip to start there) } → re-trim an ALREADY-uploaded clip (video or audio). A studio that cannot move clips refuses timeOffset rather than ignoring it.
+- split: { id, at (canvas s) } → cut a clip in two: { leftId, rightId, leftMediaId, rightMediaId, at }. The first half keeps its id. Refused (not claimed) where the studio cannot split or the time is outside the clip.
+- add_transition: { fromItemId (ends at the cut), toItemId (starts at it), transition?: { type: 'crossfade'|'dip', seconds, color } } → the same in preview and export. Split a clip, then transition between its halves, or join two clips that meet.
+- For an IMAGE on the timeline, use pinepaper_import_image with bornAt / ttl (seconds on screen).
 
 NOTES:
-- URL-based: the URL is fetched in the browser, so it must be reachable + CORS-permitted.
+- The server fetches the URL (or reads a local path / data: URL) and hands the page the bytes, so it does not need to be CORS-permitted.
 - Use the returned id with set_playback_rate / set_clip / remove, and (for video) modify/animate it like any item.
 
 VIDEO EDITING:
@@ -2065,14 +2198,16 @@ EXAMPLE: { action: 'upload_video', url: 'https://…/clip.mp4', scale: 0.5, time
         inputSchema: {
             type: 'object',
             properties: {
-                action: { type: 'string', enum: ['upload_video', 'upload_audio', 'list', 'remove', 'set_playback_rate', 'set_clip', 'set_time_remap', 'speed_ramp', 'match_cut', 'apply_track_matte', 'stop_live_matte'], description: "Media action" },
+                action: { type: 'string', enum: ['upload_video', 'upload_audio', 'list', 'remove', 'set_playback_rate', 'set_clip', 'split', 'add_transition', 'set_time_remap', 'speed_ramp', 'match_cut', 'apply_track_matte', 'stop_live_matte'], description: "Media action" },
+                transition: { type: 'object', properties: { type: { type: 'string', enum: ['crossfade', 'dip'] }, seconds: { type: 'number', exclusiveMinimum: 0, maximum: 10 }, color: { type: 'string' } }, description: "add_transition: { type ('crossfade' default | 'dip'), seconds, color (dip) }." },
+                atPlayhead: { type: 'boolean', description: 'upload_video / upload_audio: start at the current playback time (instead of timeOffset).' },
                 remapTrack: { type: 'array', items: { type: 'object', properties: { time: { type: 'number' }, value: { type: 'number' }, easing: { type: 'string' } }, required: ['time', 'value'] }, description: 'set_time_remap: canvas-seconds → source-seconds curve (≥2 points). null clears the remap.' },
                 segments: { type: 'array', items: { type: 'object', properties: { duration: { type: 'number' }, speed: { type: 'number' } }, required: ['duration', 'speed'] }, description: 'speed_ramp: consecutive {duration, speed} segments. speed 0 = freeze frame, negative = reverse.' },
                 fromItemId: { type: 'string', description: 'match_cut: outgoing shot item id.' },
                 toItemId: { type: 'string', description: 'match_cut: incoming shot item id.' },
                 subject: { type: 'string', enum: ['detect', 'bounds'], description: "match_cut: subject source — 'detect' (on-device DETR, needs consent on first use) or 'bounds'." },
                 label: { type: 'string', description: 'match_cut: narrow detection to one class ("person") when the biggest object is not the subject.' },
-                at: { type: 'number', description: 'match_cut: cut time in seconds (default 0).' },
+                at: { type: 'number', description: 'match_cut: cut time in seconds (default 0). split: the canvas time to cut at (required).' },
                 settle: { type: 'number', description: 'match_cut: seconds to relax to natural framing (default 0.8).' },
                 fade: { type: 'number', description: 'match_cut: crossfade seconds; 0 = hard cut (default 0.12).' },
                 consent: { type: 'boolean', description: 'match_cut: allow the detection model download (a first run without it returns needsConsent instead of downloading silently).' },
@@ -2088,8 +2223,9 @@ EXAMPLE: { action: 'upload_video', url: 'https://…/clip.mp4', scale: 0.5, time
                 inPoint: { type: 'number', description: 'Clip in-point (media-time s) — set_clip.' },
                 outPoint: { type: 'number', description: 'Clip out-point (media-time s, > inPoint) — set_clip.' },
                 position: { type: 'object', properties: { x: { type: 'number' }, y: { type: 'number' } }, description: 'Canvas position — upload_video.' },
-                scale: { type: 'number', description: 'Scale factor — upload_video.' },
-                timeOffset: { type: 'number', description: 'Timeline start offset (s) — upload_video / upload_audio.' },
+                scale: { type: 'number', description: "upload_video: a multiplier on the fit (contain by default), not on the source pixels; with fit: 'none', of the source pixels." },
+                fit: { type: 'string', enum: ['contain', 'cover', 'none'], description: "upload_video: size before scale — 'contain' (default), 'cover', or 'none' (source pixels)." },
+                timeOffset: { type: 'number', description: 'Timeline start offset (s) — upload_video / upload_audio; set_clip: move the clip to start here.' },
                 clipInPoint: { type: 'number', description: 'Trim in-point (s) — upload_video.' },
                 clipOutPoint: { type: 'number', description: 'Trim out-point (s) — upload_video.' },
                 volume: { type: 'number', description: 'Volume 0–1 (default 1) — upload_audio.' },
@@ -2630,6 +2766,7 @@ render_soundtrack mixes every placed sound to a WAV and writes it to a file. It
                 noiseFreq: { type: 'number', description: 'define_percussion / define_sfx: noise band centre in Hz.' },
                 hz: { type: 'number', description: 'define_percussion / define_sfx: base frequency in Hz.' },
                 pitch: { type: 'object', description: 'define_percussion / define_sfx: { from, tau } pitch glide. The glide IS the drum — omit it and a kick comes out a beep.' },
+                duration: { type: 'number', description: 'render_soundtrack: seconds to render (options.duration also works; this wins if both are given). Without either, the studio uses the timeline length (3 s when there is none).' },
                 sampleRate: { type: 'number', description: 'render_soundtrack: samples per second (default 48000).' },
                 bitDepth: { type: 'number', enum: [16, 32], description: 'render_soundtrack: 16 (default) or 32-bit float.' },
                 note: { type: 'string', description: "play_tone: scientific pitch, e.g. 'A4'." },
@@ -3571,6 +3708,10 @@ EXAMPLE — Reveal at 2s, skip first second of keyframe data, end at 4s of keyfr
                     type: 'number',
                     description: 'Stop at N seconds into the keyframe data (tail trim). Default: lastKeyframeTime.',
                 },
+                append: {
+                    type: 'boolean',
+                    description: 'Add these keys to the item\'s existing track (same-time keys merge, new values win) instead of replacing it — e.g. a button press after an entrance. Without it, a second call replaces the track. result.track says whether the track was appended to or replaced; studios without merge replace, and say so.',
+                },
             },
             required: ['itemId', 'keyframes'],
         },
@@ -4901,7 +5042,9 @@ ACTIONS:
 - update_from_instance: Promote an instance's edits back into the master. Params: instanceId
 - detach: Make an instance an ordinary independent item. Params: instanceId
 
-Overrides are the point: an instance can differ from its master and still receive master updates.`,
+Overrides are the point: an instance can differ from its master and still receive master updates.
+
+Instances carry the master's LOOK (geometry, style, text), not its animation: instantiate and sync copy what the master is, not its keyframes or animations. To animate instances, animate each one (keyframe_animate on its instanceId, or stagger across them).`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -7739,7 +7882,7 @@ NOTE: For diagrams (flowcharts, UML), use pinepaper_create_diagram_shape + pinep
 
 ⚠️ EVERY operation executes LIVE on the canvas. Calling this twice DOUBLES all items. Call ONCE per pipeline.
 
-⚠️ SIZING: All positions/sizes MUST fit within the canvas. start_job returns canvasSize. Keep items within 5%-95% of canvas width/height. Max canvas: 8192x8192.
+⚠️ SIZING: All positions/sizes MUST fit within the canvas. start_job returns canvasSize. Keep items within 5%-95% of canvas width/height. Max canvas: 16384 per side (above 8192, Safari / iOS may fail).
 
 ONTOLOGY PREFLIGHT: Before code generation, this tool validates itemType, relationType, effectType, and generatorName against the canonical PinePaper vocabulary. A typo (e.g. "circel") returns a structured VALIDATION_ERROR with the operation index, the offending field, the canonical valid list, and a suggested fix — fix and retry rather than guessing. Pass skipValidation: true to bypass when intentionally using experimental vocabulary.
 
@@ -7826,8 +7969,8 @@ EXAMPLE — Animated sky scene with timed reveals:
                                 description: 'Operation type',
                             },
                             // Canvas setup
-                            width: { type: 'number', description: 'Canvas width for set_canvas_size (100-8192)' },
-                            height: { type: 'number', description: 'Canvas height for set_canvas_size (100-8192)' },
+                            width: { type: 'number', description: 'Canvas width for set_canvas_size (100-16384)' },
+                            height: { type: 'number', description: 'Canvas height for set_canvas_size (100-16384)' },
                             preset: { type: 'string', description: 'Canvas preset for set_canvas_size' },
                             backgroundColor: { type: 'string', description: 'For set_background: hex color' },
                             generatorName: {
@@ -8050,6 +8193,8 @@ VERIFY MOTION BEFORE YOU RENDER. An export takes seconds to minutes and shows yo
                 alphaQuantizer: { type: 'integer', minimum: 0, maximum: 63, description: 'webm with transparent: alpha-stream quality, 0 = lossless … 63.' },
                 loop: { anyOf: [{ type: 'boolean' }, { type: 'integer', minimum: 0, maximum: 1000 }], description: 'gif / apng: true = loop forever, false / 0 / 1 = play once, n = play n times (email clients often want a few plays, not forever). Refused on video formats — see SEAMLESS LOOPS.' },
                 broadcast: { type: 'boolean', description: 'mp4 only: broadcast-safe — BT.709, limited range (16-235), tagged bt709, constant bitrate with an 8 Mbps floor at 720p+ (4 below). result.video reports what the encoder did.' },
+                frames: { type: 'integer', minimum: 1, maximum: 36000, description: 'Animated formats: exactly this many frames instead of duration. A duration makes ceil(duration x fps) frames (7.91667 s at 24 fps is 191, not 190), so use frames for frame-exact segments.' },
+                deterministic: { type: 'boolean', description: 'mp4 / webm: byte-identical files for the same scene (pins the container timestamps), so exports can be checksummed or cached by hash.' },
                 broadcastHeadroom: { type: 'integer', minimum: 0, maximum: 40, description: 'mp4 with broadcast only, default 12: luma codes kept clear at both ends, so encoder ringing stays legal (12 measured clean on hard edges; 4 = ~100x fewer out-of-range samples, 12 = ~1000x; never zero). Fidelity raises luma_out_of_range with the legaliser command when any remain.' },
                 bitrate: { type: 'integer', minimum: 100000, maximum: 200000000, description: 'mp4 / webm: target bits/s, replacing the quality-derived one. The browser encoder treats it as a CEILING; result.video.achievedBitrate is what it produced.' },
                 minBitrate: { type: 'integer', minimum: 100000, maximum: 200000000, description: 'mp4 / webm: a floor; a miss is a fidelity warning naming the re-encode a delivery spec needs.' },
@@ -8075,7 +8220,7 @@ VERIFY MOTION BEFORE YOU RENDER. An export takes seconds to minutes and shows yo
                     properties: {
                         x: { type: 'number' }, y: { type: 'number' },
                         width: { type: 'number', exclusiveMinimum: 0 }, height: { type: 'number', exclusiveMinimum: 0 },
-                        outputWidth: { type: 'integer', minimum: 1, maximum: 8192 }, outputHeight: { type: 'integer', minimum: 1, maximum: 8192 },
+                        outputWidth: { type: 'integer', minimum: 1, maximum: 16384 }, outputHeight: { type: 'integer', minimum: 1, maximum: 16384 },
                         excludeForeign: { type: 'boolean', description: 'Default true: an item reaching into the region but centred outside it (a neighbouring card overflow) is left out of this image; result.excludedItems names them. false renders everything that touches the region.' },
                     },
                     required: ['x', 'y', 'width', 'height'],
@@ -8107,8 +8252,8 @@ VERIFY MOTION BEFORE YOU RENDER. An export takes seconds to minutes and shows yo
                 duration: {
                     type: 'number',
                     minimum: 0.5,
-                    maximum: 60,
-                    description: 'Video duration in seconds for mp4/webm/gif (default 5). Max 60 for mp4/webm; GIF is capped at 15 because it has no bitrate target, so size scales with frames × dimensions — use mp4/webm for longer clips. Static formats ignore this. If you set play_timeline to N seconds, pass the same N here.',
+                    maximum: 600,
+                    description: 'Video duration in seconds for mp4/webm/gif (default 5). Max 600 for mp4/webm (past about a minute the file is paged back from the studio\'s export store); GIF is capped at 15 because it has no bitrate target, so size scales with frames × dimensions — use mp4/webm for longer clips. The file has ceil(duration × fps) frames — for an exact count use frames instead. Static formats ignore this. If you set play_timeline to N seconds, pass the same N here.',
                 },
             },
             // Nothing is required: platform defaults to 'auto', which is the canvas's